# NAME Pepper - A command-line EPP client. # DESCRIPTION Pepper is a command-line client for the EPP protocol. It's written in Perl and uses the [Net::EPP](https://metacpan.org/pod/Net%3A%3AEPP) module. # USAGE pepper [OPTIONS] Available command-line options: - `--help` - show help and exit. - `--host=HOST` - sets the host to connect to. - `--port=PORT` - sets the port. Defaults to 700. - `--timeout=TIMEOUT` - sets the timeout. Defaults to 3. - `--user=USER` - sets the client ID. - `--pass=PASS` - sets the client password. - `--newpw=PASS` - specify a new password to replace the current password. - `--login-security` - force the use of the Login Security extension (RFC 8807). - `--cert=FILE` - specify the client certificate to use to connect. - `--key=FILE` - specify the private key for the client certificate. - `--exec=COMMAND` - specify a command to execute. If not provided, pepper goes into interactive mode. - `--insecure` - disable SSL certificate checks. - `--lang=LANG` - set the language when logging in. - `--debug` - debug mode, makes `Net::EPP::Simple` verbose. # USAGE MODES Pepper supports two usage modes: - 1. Interactive mode: this is the default mode. Pepper will provide a command prompt (with history and line editing capabilities) allowing you to input commands manually. - 2. Script mode: if Pepper's `STDIN` is fed a stream of text (ie it's not attached to a terminal) then commands will be read from `STDIN` and executed sequentially. Pepper will exit once EOF is reached. # SYNTAX Once running in interactive mode, Pepper provides a simple command-line interface. The available commands are listed below. ## Getting Help Use `help COMMAND` at any time to get information about that command. Where a command supports different object types (ie domain, host, contact), use `help command-type`, ie `help create-domain`. ## Connection Management - `host HOST` - sets the host to connect to. - `port PORT` - sets the port. Defaults to 700. - `ssl on|off` - enable/disable SSL (default is on) - `key FILE` - sets the private key - `cert FILE` - sets the client certificate. - `timeout TIMEOUT` - sets the timeout - `connect` - connect to the server. - `hello` - gets the greeting from server. - `exit` - quit the program (logging out if necessary) ## Session Management - `id USER` - sets the client ID. - `pw PASS` - sets the client password. - `login` - log in. - `logout` - log out. - `poll req` - requests the most recent poll message. - `poll ack ID` - acknowledge the poll message with ID `ID`. ## Query Commands ### Availability Checks check TYPE OBJECT This checks the availability of an object. `TYPE` is one of `domain`, `host`, `contact`, `claims` or `fee`. See ["Claims and fee Checks"](#claims-and-fee-checks) for more information about the latter two. ### Object Information info TYPE OBJECT [PARAMS] Get object information. `TYPE` is one of `domain`, `host`, `contact`. For domain objects, `PARAMS` can be `AUTHINFO [HOSTS]`, where `AUTHINFO` is the domain's authInfo code, and the optional `HOSTS` is the value of the "hosts" attribute (ie `all`, which is the default, or `del`, `sub`, or `none`). If you want to set `HOSTS` but don't know the authInfo, use an empty quoted string (ie `""`) as `AUTHINFO`. For contact objects, `PARAMS` can be the contact's authInfo. ## Transform Commands - `create domain PARAMS` - create a domain object. See ["Creating Domain Objects"](#creating-domain-objects) for more information. - `create host PARAMS` - create a host object. See ["Creating Host Objects"](#creating-host-objects) for more information. - `clone TYPE OLD NEW` - clone a domain or contact object `OLD` into a new object identified by `NEW`. `TYPE` is one of `domain` or `contact`. - `update TYPE OBJECT CHANGES` - update an object. `TYPE` is one of `domain`, `host`, or `contact`. See ["Object Updates"](#object-updates) for further information. - `renew DOMAIN PERIOD [EXDATE]` - renew a domain (1 year by default). If you do not provide the `EXDATE` argument, pepper will perform an `` command to get it from the server. - `transfer PARAMS` - object transfer management See ["Object Transfers"](#object-transfers) for more information. - `delete TYPE OBJECT` - delete an object. `TYPE` is one of `domain`, `host`, or `contact`. - `restore DOMAIN` - submit an RGP restore request for a domain. ## Miscellaneous Commands - `send FILE` - send the contents of `FILE` as an EPP command. - `BEGIN` - begin inputting a frame to send to the server, end with "`END`". - `edit` - Invoke `$EDITOR` and send the resulting file. ## Claims and fee Checks Pepper provides limited support for the the Launch and Fee extensions: ### Claims Check The following command will extend the standard <check> command to perform a claims check as per Section 3.1.1. of [draft-ietf-eppext-launchphase](https://metacpan.org/pod/draft-ietf-eppext-launchphase). pepper> check claims example.xyz ### Fee Check The following command will extend the standard <check> command to perform a fee check as per Section 3.1.1. of [draft-brown-epp-fees-02](https://metacpan.org/pod/draft-brown-epp-fees-02). pepper> check fee example.xyz COMMAND [CURRENCY [PERIOD]] `COMMAND` must be one of: `create`, `renew`, `transfer`, or `restore`. `CURRENCY` is OPTIONAL but if provided, must be a three-character currency code. `PERIOD` is also OPTIONAL but if provided, must be an integer between 1 and 99. ## Creating Objects ### Creating Domain Objects There are two ways of creating a domain: clone domain OLD NEW This command creates the domain `NEW` using the same contacts and nameservers as `OLD`. create domain DOMAIN PARAMS This command creates a domain according to the parameters specified after the domain. `PARAMS` consists of pairs of name and (optionally quoted) value pairs as follows: - `period` - the registration period. Defaults to 1 year. - `registrant` - the registrant. - `admin` - the admin contact. - `tech` - the tech contact. - `billing` - the billing contact. - `ns` - add a nameserver. - `authinfo` - authInfo code. A random string will be used if not provided. Example: pepper (id@host)> create domain example.xyz period 1 registrant sh8013 admin sh8013 tech sh8013 billing sh8013 ns ns0.example.com ns ns1.example.net ### Creating Host Objects Syntax: create host HOSTNAME [IP [IP [IP [...]]]] Create a host object with the specified `HOSTNAME`. IP address may also be specified: IPv4 and IPv6 addresses are automatically detected. ### Creating Contact Objects There are two ways of creating a contact: clone contact OLD NEW This command creates the contact `NEW` using the same data as `OLD`. create contact PARAMS This command creates a contact object according to the parameters specified. `PARAMS` consists of pairs of name and (optionally quoted) value pairs as follows: - `id` - contact ID. If not provided, a random 16-charater ID will be generated - `type` - specify the "type" attribute for the postal address information. Only one type is supported. Possible values are "int" (default) and "loc". - `name` - contact name - `org` - contact organisation - `street` - street address, may be provided multiple times - `city` - city - `sp` - state/province - `pc` - postcode - `cc` - ISO-3166-alpha2 country code - `voice` - E164 voice number - `fax` - E164 fax number - `email` - email address - `authinfo` - authInfo code. A random string will be used if not provided. Example: pepper (id@host)> create contact id "sh8013" name "John Doe" org "Example Inc." type int street "123 Example Dr." city Dulles sp VA pc 20166-6503 cc US voice +1.7035555555 email jdoe@example.com ## Object Updates Objects may be updated using the `update` command. ### Domain Updates update domain DOMAIN CHANGES The `CHANGES` argument consists of groups of three values: an action (ie `add`, `rem` or `chg`), followed by a property name (e.g. `ns`, a contact type (such as `admin`, `tech` or `billing`) or `status`), followed by a value. Example: update domain example.com add ns ns0.example.com update domain example.com rem ns ns0.example.com update domain example.com add status clientUpdateProhibited update domain example.com rem status clientHold update domain example.com add admin H12345 update domain example.com rem tech H54321 update domain example.com chg registrant H54321 update domain example.cm chg authinfo foo2bar Multiple changes can be combined in a single command: update domain example.com add status clientUpdateProhibited rem ns ns0.example.com chg registrant H54321 ### Host Updates Syntax: update host HOSTNAME CHANGES The `CHANGES` argument consists of groups of three values: an action (ie `add`, `rem` or `chg`), followed by a property name (ie `addr`, `status` or `name`), followed by a value (which may be quoted). Examples: update host ns0.example.com add status clientUpdateProhibited update host ns0.example.com rem addr 10.0.0.1 update host ns0.example.com chg name ns0.example.net Multiple changes can be combined in a single command: update host ns0.example.com add status clientUpdateProhibited rem addr 10.0.0.1 add addr 1::1 chg name ns0.example.net ### Contact Updates Not currently implemented. ## Object Transfers Object transfers may be managed with the `transfer` command. Usage: transfer TYPE OBJECT CMD [AUTHINFO [PERIOD]] where: - `TYPE` - `domain` or `contact` - `OBJECT` - domain name or contact ID - `CMD` - one of (`request`, `query`, `approve`, `reject`, or `cancel`) - `AUTHINFO` - authInfo code (used with `request` only) - `PERIOD` - additional validity period (used with domain `request` only) ## Errors If you prefix a command with a `!` character, then Pepper will end the session if an EPP command fails (that is, if the result code of the response is 2000 or higher). This is mostly useful in scripting mode where you may want the script to terminate if an error occurs. Example usage: !create domain example.com authinfo foo2bar update domain example.com add ns ns0.example.com In the above example, Pepper will end the session if the first command fails, since there is no point in running the second command if the first has failed. # INSTALLATION To install, run: cpanm --sudo App::pepper If [Term::ReadLine::Gnu](https://metacpan.org/pod/Term%3A%3AReadLine%3A%3AGnu) is available, then Pepper can provide a richer interactive command line, with support for history and rich command editing. # RUNNING VIA DOCKER The [git repository](https://github.com/gbxyz/pepper) contains a `Dockerfile` that can be used to build an image on your local system. Alternatively, you can pull the [image from Docker Hub](https://hub.docker.com/repository/docker/gbxyz/pepper/general): $ docker pull gbxyz/pepper $ docker run -it gbxyz/pepper --help # LICENSE Copyright 2014 - 2023 CentralNic Group plc. This program is Free Software; you can use it and/or modify it under the same terms as Perl itself.