Unverified Commit bf9c93cc authored by Gavin Brown's avatar Gavin Brown
Browse files

documentation update. implement newpw support and --key and --cert command line options

parent 0418d8e4
......@@ -8,195 +8,154 @@ Pepper is a command-line client for the EPP protocol. It's written in Perl and u
# USAGE
pepper [--host=HOST] [--port=PORT] [--timeout=TIMEOUT] [--user=USER] [--pass=PASS] [--exec=COMMAND]
- `--host=HOST`
Specify the host name to connect to.
- `--port=PORT`
Specify the port. Defaults to 700.
- `--timeout=TIMEOUT`
Specify the timeout. Defaults to 3.
- `--user=USER`
Specify user ID.
- `--pass=PASS`
Specify password.
- `--exec=COMMAND`
Specify command to execute. May be used multiple times. See [SYNTAX](https://metacpan.org/pod/SYNTAX) for more details.
- `--insecure`
Disable SSL certificate checks.
- `--lang=LANG`
Specify language.
pepper [OPTIONS]
Available command-line options:
- `--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.
- `--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.
# SYNTAX
Once running, Pepper provides a simple command line interface. The available commands are listed below:
- `help`
display manual
- `host HOST`
set hostname
- `port PORT`
set port (defaults to 700)
- `ssl on|off`
Once running, Pepper provides a simple command line interface. The available commands are listed below. You can use the `help` command to view this list when pepper is running.
enable/disable SSL (defaults to on)
## Connection Management
- `timeout TIMEOUT`
- `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)
set timeout (default 5 seconds)
## Session Management
- `id USER`
- `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`.
set username
## Query Commands
- `pw PASS`
- `check TYPE OBJECT` - 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.
- `info TYPE OBJECT` - get object information. `TYPE` is one of `domain`, `host`, `contact`.
set password
## Transform Commands
- `connect`
- `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 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 `<info>` command to get it from the server.
- `transfer PARAMS` - object transfer management See ["Object Transfers"](#object-transfers) for more information.
- `delete TYPE ID` - delete an object. `TYPE` is one of `domain`, `host`, or `contact`.
- `restore DOMAIN` - submit an RGP restore request for a domain.
connect to server
## Miscellaneous Commands
- `login`
- `send FILE` - send the contents of `FILE`.
- `BEGIN` - begin inputting a frame to send to the server, end with "`END`".
- `edit` - Invoke `$EDITOR` and send the resulting file.
log in
## Claims and fee Checks
- `logout`
log out
- `hello`
retrieve greeting from server
- `poll req`
request most recent poll message
- `poll ack ID`
acknowledge message `ID`
- `check TYPE OBJECT`
check availability of object (`TYPE` is one of `domain`, `host`, `contact`, `claims`, `fee`). See ["CLAIMS AND FEE CHECKS"](#claims-and-fee-checks) for more information about the latter two.
- `info TYPE OBJECT`
retrieve object information (`TYPE` is one of `domain`, `host`, `contact`)
- `send FILE`
send the contents of `FILE`
- `BEGIN`
begin inputting a frame to send to the server, end with "`END`"
- `edit`
Invoke `$EDITOR` and send the resulting file
- `transfer PARAMS`
Pepper provides limited support for the the launch and fee extensions:
object transfer management See ["OBJECT TRANSFERS"](#object-transfers) for more information.
### Claims Check
- `clone TYPE OLD NEW`
The following command will extend the standard &lt;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).
clone a domain or contact object `OLD` into a new object identified by `NEW` (`TYPE` is one of `domain`, `contact`)
pepper> check claims example.xyz
- `delete TYPE ID`
### Fee Check
delete an object (`TYPE` is one of `domain`, `host`, `contact`)
The following command will extend the standard &lt;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).
- `renew DOMAIN PERIOD [EXPDATE]`
pepper> check fee example.xyz COMMAND [CURRENCY [PERIOD]]
renew a domain (1 year by default). If you do not provide the `CUREXPDATE` argument, pepper will perform an `<info>` command to get it from the server.
`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.
- `restore DOMAIN`
## Creating Domain and Contact Objects
submit an RGP restore request for a domain
Domain and contact objects can currently only be created using the `clone` command.
- `create host PARAMS`
## Creating Host Objects
create a host object. See ["CREATING HOST OBJECTS"](#creating-host-objects) for more information.
Syntax:
- `exit`
create host HOSTNAME [IP [IP [IP [...]]]]
quit the program (logging out if necessary)
Create a host object with the specified `HOSTNAME`. IP address may also be
specified: IPv4 and IPv6 addresses are automatically detected.
## OBJECT UPDATES
## Object Updates
Objects may be updated using the `update` command.
### Domain Updates
update domain HOSTNAME CHANGES
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 add ns ns0.example.com
update domain example.com rem ns ns0.example.com
update domain example.com rem ns ns0.example.com
update domain example.com add status clientUpdateProhibited
update domain example.com add status clientUpdateProhibited
update domain example.com rem status clientHold
update domain example.com rem status clientHold
update domain example.com add admin H12345
update domain example.com add admin H12345
update domain example.com rem tech H54321
update domain example.com rem tech H54321
update domain example.com chg registrant H54321
update domain example.com chg registrant H54321
update domain example.cm chg authinfo foo2bar
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
update domain example.com add status clientUpdateProhibited rem ns ns0.example.com chg registrant H54321
### Host Updates
Syntax:
update host HOSTNAME CHANGES
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.
Examples:
update host ns0.example.com add status clientUpdateProhibited
update host ns0.example.com add status clientUpdateProhibited
update host ns0.example.com rem addr 10.0.0.1
update host ns0.example.com rem addr 10.0.0.1
update host ns0.example.com chg name ns0.example.net
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
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
......@@ -206,75 +165,27 @@ Not currently implemented.
Object transfers may be managed with the `transfer` command. Usage:
transfer TYPE OBJECT CMD [AUTHINFO [PERIOD]]
transfer TYPE OBJECT CMD [AUTHINFO [PERIOD]]
where:
- `TYPE`
one of `domain`, `contact`
- `OBJECT`
domain name or contact ID
- `CMD`
one of (`request`, `query`, `approve`, `reject`, `cancel`)
- `AUTHINFO`
authInfo code (used with `request` only)
- `PERIOD`
additional validity period (used with domain `request` only)
## CLAIMS AND FEE CHECKS
Pepper provides limited support for the the launch and fee extensions:
### CLAIMS CHECK
The following command will extend the standard &lt;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 &lt;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`, `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 DOMAIN AND CONTACT OBJECTS
Domains and contacts can be created using the `clone` command.
## 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.
- `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)
# INSTALLATION
Pepper requires that the following Perl modules be installed:
Pepper uses these modules:
- `Term::ReadLine::Gnu` (and `Term::ReadLine`)
- `Net::EPP::Simple` (from `Net::EPP`, in turn requires `IO::Socket::SSL` and `XML::LibXML`)
- `Text::ParseWords`
- `Mozilla::CA`
- [Term::ANSIColor](https://metacpan.org/pod/Term::ANSIColor)
- [Term::ReadLine::Gnu](https://metacpan.org/pod/Term::ReadLine::Gnu) (and [Term::ReadLine](https://metacpan.org/pod/Term::ReadLine))
- [Net::EPP::Simple](https://metacpan.org/pod/Net::EPP::Simple) (from [Net::EPP](https://metacpan.org/pod/Net::EPP), which in turn uses [IO::Socket::SSL](https://metacpan.org/pod/IO::Socket::SSL) and [XML::LibXML](https://metacpan.org/pod/XML::LibXML))
- [Text::ParseWords](https://metacpan.org/pod/Text::ParseWords)
- [Mozilla::CA](https://metacpan.org/pod/Mozilla::CA)
This can be installed using one of the various CPAN clients, or as packages from your operating system vendor.
They can be installed using one of the various CPAN clients, or as packages from your operating system vendor.
# LICENSE
......
......@@ -41,23 +41,8 @@ sub send_frame {
return $self->SUPER::send_frame($frame, $wfcheck);
}
sub request {
my ($self, $frame) = @_;
my $response = $self->SUPER::request($frame);
if (!$response) {
$self->{'outfh'}->print(sprintf("%s%04d%s %s\n", color($Net::EPP::Simple::Code < 2000 ? 'green' : 'red'), $Net::EPP::Simple::Code, color('reset'), $Net::EPP::Simple::Message));
} else {
return $response;
}
}
package Pepper::Higlighter;
use Term::ANSIColor;
use Data::Dumper;
use strict;
use HTML::Entities qw(encode_entities_numeric);
use vars qw($fh);
......@@ -112,6 +97,7 @@ GetOptions($opt,
'host=s',
'user=s',
'pass=s',
'newpw=s',
'port=i',
'timeout=i',
'help',
......@@ -119,6 +105,8 @@ GetOptions($opt,
'insecure',
'lang=s',
'debug',
'cert=s',
'key=s',
);
my $handlers = {
......@@ -129,6 +117,7 @@ my $handlers = {
'credentials' => \&handle_credentials,
'id' => \&handle_id,
'pw' => \&handle_pw,
'newpw' => \&handle_newpw,
'connect' => \&handle_connect,
'login' => \&handle_login,
'logout' => \&handle_logout,
......@@ -186,6 +175,9 @@ execute_command(sprintf('port %d', $opt->{'port'})) if ($opt->{'port'});
execute_command(sprintf('host %s', $opt->{'host'})) if ($opt->{'host'});
execute_command(sprintf('id %s', $opt->{'user'})) if ($opt->{'user'});
execute_command(sprintf('pw %s', $opt->{'pass'})) if ($opt->{'pass'});
execute_command(sprintf('newpw %s', $opt->{'newpw'})) if ($opt->{'newpw'});
execute_command(sprintf('cert %s', $opt->{'cert'})) if ($opt->{'cert'});
execute_command(sprintf('key %s', $opt->{'key'})) if ($opt->{'key'});
if ($epp->{'user'} ne '' && $epp->{'pass'} ne '') {
execute_command('login');
......@@ -208,8 +200,9 @@ if ($opt->{'exec'} ne '') {
my $last;
while (1) {
$prompt = sprintf('pepper[%s@%s]> ', $epp->{'user'}, $epp->{'host'}) if ($epp->authenticated);
my $command = $term->readline($prompt);
alarm(0);
if (!defined($command)) {
last;
......@@ -231,7 +224,7 @@ $term->WriteHistory($histfile);
handle_logout() if ($epp->connected && $epp->authenticated);
$epp->disconnect if ($epp->connected);
note('bye!');
note('Bye!');
sub execute_command {
my $line = shift;
......@@ -304,7 +297,7 @@ sub handle_connect {
return error('No host specified');
} else {
note('Connecting to %s', $epp->{'host'});
note('Connecting to %s...', $epp->{'host'});
$epp->{'quiet'} = 1;
my $result = $epp->_connect(undef);
......@@ -356,6 +349,17 @@ sub handle_pw {
}
}
sub handle_newpw {
if ($epp->authenticated) {
return error("Already authenticated");
} else {
$epp->{'newPW'} = shift;
note("New password set to '%s'", ('*' x length($epp->{'newPW'})));
}
}
sub handle_login {
my $verbose = shift;
if (!$epp->connected) {
......@@ -371,10 +375,12 @@ sub handle_login {
return error('No credentials specified');
} else {
note("Attempting to login as '%s'...", $epp->{'user'});
$epp->{'quiet'} = ($verbose ? 0 : 1);
my $result = $epp->_login;
$epp->{'quiet'} = 0;
note("%s%04d%s %s", color($Net::EPP::Simple::Code < 2000 ? 'green' : 'red'), $Net::EPP::Simple::Code, color('reset'), $Net::EPP::Simple::Message);
note('Logged in OK!') if ($result);
return $result;
}
}
......@@ -724,8 +730,17 @@ sub handle_edit {
} else {
my $file = tmpnam();
if (0 != system(sprintf("%s %s", $ENV{'EDITOR'}, quotemeta($file)))) {
error("$ENV{'EDITOR'} exited abnormally");
open(FILE, ">$file");
print FILE Net::EPP::Frame->new('command')->toString(2);
close(FILE);
my $cmd = ($ENV{'EDITOR'} || '/usr/bin/vi');
my ($cmd, @args) = split(/[ \t]+/, $cmd);
push(@args, $file);
if (0 != system($cmd, @args)) {
error("$cmd exited abnormally");
} else {
if (!-e $file || 0 == (stat($file))[7]) {
......@@ -737,7 +752,7 @@ sub handle_edit {
my $frame = <FILE>;
close(FILE);
unlink($file);
$epp->request($frame);
return $epp->request($frame);
}
}
}
......@@ -997,203 +1012,210 @@ Pepper is a command-line client for the EPP protocol. It's written in Perl and u
=head1 USAGE
pepper [--host=HOST] [--port=PORT] [--timeout=TIMEOUT] [--user=USER] [--pass=PASS] [--exec=COMMAND]
pepper [OPTIONS]
Available command-line options:
=over
=item C<--host=HOST>
=item C<--host=HOST> - sets the host to connect to.
Specify the host name to connect to.
=item C<--port=PORT> - sets the port. Defaults to 700.
=item C<--port=PORT>
=item C<--timeout=TIMEOUT> - sets the timeout. Defaults to 3.
Specify the port. Defaults to 700.
=item C<--user=USER> - sets the client ID.
=item C<--timeout=TIMEOUT>
=item C<--pass=PASS> - sets the client password.
Specify the timeout. Defaults to 3.
=item C<--cert=FILE> - specify the client certificate to use to connect.
=item C<--user=USER>
=item C<--key=FILE> - specify the private key for the client certificate.
Specify user ID.
=item C<--exec=COMMAND> - specify a command to execute. If not provided, pepper goes into interactive mode.
=item C<--pass=PASS>
=item C<--insecure> - disable SSL certificate checks.
Specify password.
=item C<--lang=LANG> - set the language when logging in.
=item C<--exec=COMMAND>
=item C<--debug> - debug mode, makes C<Net::EPP::Simple> verbose.
Specify command to execute. May be used multiple times. See L<SYNTAX> for more details.
=back
=item C<--insecure>
=head1 SYNTAX
Disable SSL certificate checks.
Once running, Pepper provides a simple command line interface. The available commands are listed below. You can use the C<help> command to view this list when pepper is running.
=item C<--lang=LANG>
=head2 Connection Management
Specify language.
=over
=back
=item C<host HOST> - sets the host to connect to.
=head1 SYNTAX
=item C<port PORT> - sets the port. Defaults to 700.
Once running, Pepper provides a simple command line interface. The available commands are listed below:
=item C<ssl on|off> - enable/disable SSL (default is on)
=over
=item C<key FILE> - sets the private key
=item C<help>
=item C<cert FILE> - sets the client certificate.
display manual
=item C<timeout TIMEOUT> - sets the timeout
=item C<host HOST>
=item C<connect> - connect to the server.
set hostname
=item C<hello> - gets the greeting from server.
=item C<port PORT>
=item C<exit> - quit the program (logging out if necessary)
set port (defaults to 700)
=back
=item C<ssl on|off>
=head2 Session Management
enable/disable SSL (defaults to on)
=over
=item C<timeout TIMEOUT>
=item C<id USER> - sets the client ID.
set timeout (default 5 seconds)
=item C<pw PASS> - sets the client password.
=item C<id USER>
=item C<login> - log in.
set username
=item C<logout> - log out.
=item C<pw PASS>
=item C<poll req> - requests the most recent poll message.
set password
=item C<poll ack ID> - acknowledge the poll message with ID C<ID>.
=item C<connect>
=back
connect to server
=head2 Query Commands
=item C<login>
=over
log in
=item C<check TYPE OBJECT> - checks the availability of an object. C<TYPE> is one of C<domain>, C<host>, C<contact>, C<claims> or C<fee>. See L<Claims and fee Checks> for more information about the latter two.
=item C<logout>
=item C<info TYPE OBJECT> - get object information. C<TYPE> is one of C<domain>, C<host>, C<contact>.
log out
=back
=item C<hello>
=head2 Transform Commands
retrieve greeting from server
=over
=item C<poll req>
=item C<create host PARAMS> - create a host object. See L<Creating Host Objects> for more information.
requ