$Id$ -*- Text -*- Preliminary operation instructions for rpkid et al. These are the production-side RPKI tools, for Internet Registries (RIRs, LIRs, etc). See ../rcynic/README for relying party tools. See INSTALLATION for how to install the software. At present the package is intended to be run out of the scripts directory. In addition to the library routines in the scripts/rpki/ directory, the package includes the following programs: rpkid.py The main RPKI engine daemon rootd.py A separate daemon for handling the root of an RPKI certificate tree. This is essentially a stripped down version of rpkid with no SQL database, no left-right protocol implementation, and only the parent side of the up-down protocol. It's separate because the root is a special case in several ways and it was simpler to keep the special cases out of the main daemon. irdbd.py A sample implementation of an IR database daemon. rpkid calls into this to perform lookups via the left-right protocol. irbe-cli.py A command-line client for the left-right control protocol. irbe-setup.py An example of a script to set up the mappings between the IRDB and rpkid's own database, using the left-right control protocol. cronjob.py A trivial HTTP client used to drive rpkid cron events. testbed.py A test tool for running a collection of rpkid and irdb instances under common control, driven by a unified test script. testpoke.py A simple client for the up-down protocol, mostly compatable with APNIC's rpki_poke.pl tool. Most of these programs take configuration files in a common format similar to that used by the OpenSSL command line tool. The test programs also take input in YAML format to drive the tests. Runs of the testbed.py test tool will generate a fairly complete set configuration files which may be useful as examples. Basic operation consists of creating the appropriate MySQL databases, starting rpkid, rootd, and irdbd, using the left-right control protocol to set up rpkid's internal state, and setting up a cron job to invoke rpkid's cron action at regular intervals. All other operations should occur either as a result of cron events or as a result of incoming left-right and up-down protocol requests. Note that the publication protocol isn't fully specified yet, much less implmenented. At the moment rpkid just writes its outputs to a local directory tree. Note that the full event-driven model for rpkid hasn't yet been implemented. The design is intended to allow an arbitrary number of hosted RPKI engines to run in a single rpkid instance, but without the event-driven tasking model one has to set up a separate rpkid instance for each hosted RPKI engine. At present the daemon programs all run in foreground, that is, if one wants them to run in background one must do so manually, eg, using Bourne shell syntax: $ python whatever.py & $ echo >whatever.pid "$!" All of the daemons use syslog. At present they all set LOG_PERROR, so all logging also goes to stderr. ---------------------------------------------------------------- rpkid.py: rpkid is the main RPKI engine daemon. Configuration of rpkid is a two step process: a config file to bootstrap rpkid to the point where it can speak using the left-right protocol, followed by dynamic configuration via the left-right protocol. In production use the latter stage would be handled by the IRBE stub; for test and develoment purposes it's handled by the irbe-cli.py command line interface or by the testbed.py test framework. rpkid stores dynamic data in an SQL database, which must have been created for it, as explained in the installation guide. The default config file is rpkid.conf, start rpkid with "-c filename" to choose a different config file. All options are in the section "[rpkid]". Certificates, keys, and trust anchors may be in either DER or PEM format. Config file options: startup-message: String to log on startup, useful when debugging a collection of rpkid instances at once. sql-username: Username to hand to MySQL when connecting to rpkid's database. sql-database: MySQL's database name for rpkid's database. sql-password: Password to hand to MySQL when connecting to rpkid's database. cms-ta-irdb: Name of file containing CMS trust anchor to use when authenticating messages from irdbd. cms-ta-irdb: Name of file containing CMS trust anchor to use when authenticating control messages from IRBE. cms-key: Name of file containing RSA key to use when signing CMS messages to IRBE or irdbd. cms-certs: Name(s) of file(s) containing certificate(s) to include in CMS wrapper when signing messages to IRBE or irdbd. You can specify more than one certificate using OpenSSL-style subscripts: cms-certs.0, cms-certs.1, etc. https-key: Name of file containing RSA key to use, both in the HTTPS server role (for both up-down and left-right protocols) and in the HTTPS client role (left-right protocol only). https-certs: Name(s) of file(s) containing certificate(s) to use in same contexts where https-key is used. You can specify more than one certificate using OpenSSL-style subscripts: https-certs.0, https-certs.1, etc. https-ta: Name of file containing trust anchor to use when verifying irdbd's HTTPS server certificate. irdb-url: Service URL for irdbd. Must be a https:// URL. https-server-host: Hostname or IP address on which to listen for HTTPS connections. Default is localhost. https-server-port: TCP port on which to listen for HTTPS connections. publication-kludge-base: [TEMPORARY] Local directory under which generated certificates etc should be published. This is a temporary expedient until the publication protocol is defined and implemented. Default is "publication/" ---------------------------------------------------------------- rootd.py: rootd is a stripped down implmenetation of (only) the server side of the up-down protocol. It's a separate program because the root certificate of an RPKI certificate tree requires special handling and may also require a special handling policy. rootd is a simple implementation intended for test use, it's not suitable for use in a production system. All configuration comes via the config file. The default config file is rootd.conf, start rootd with "-c filename" to choose a different config file. All options are in the section "[rootd]". Certificates, keys, and trust anchors may be in either DER or PEM format. Config file options: cms-ta: Name of file containing trust anchor to use when verifying CMS up-down queries. cms-key: Name of file containing RSA key to use when signing CMS up-down replies. cms-certs: Name(s) of file(s) containing certificate(s) to include in CMS wrapper when signing up-down replies. You can specify more than one certificate using OpenSSL-style subscripts: cms-certs.0, cms-certs.1, etc. https-key: Name of file containing RSA key to use in the HTTPS server role for the up-down protocol. https-certs: Name(s) of file(s) containing certificate(s) to use in the HTTPS server role for the up-down protocol. You can specify more than one certificate using OpenSSL-style subscripts: https-certs.0, https-certs.1, etc. https-server-host: Hostname or IP address on which to listen for HTTPS connections. Default is localhost. https-server-port: TCP port on which to listen for HTTPS connections. rpki-key: Name of file containing RSA key to use in signing resource certificates. rpki-issuer: Name of file containing self-signed root resource certificate corresponding to rpki-key. rpki-subject-filename: Name of file that rootd should use to save the one and only certificate it issues. rpki-pkcs10-filename: Name of file that rootd should use when saving a copy of the received PKCS #10 request for a resource certificate. This is only used for debugging. Default is not to save the PKCS #10 request. ---------------------------------------------------------------- irdbd.py: irdbd is a sample implemntation of the server side of the IRDB callback subset of the left-right protocol. In production use this service is a function of the IRBE stub; irdbd may be suitable for production use in simple cases, but an IR with a complex IRDB may need to extend or rewrite irdbd. irdbd requires a pre-populated database to represent the IR's customers. irdbd expects this database to use the SQL schema defined in docs/sample-irdb.sql. Once this database has been populated, the IRBE stub needs to create the appropriate objects in rpkid's database via the control subset of the left-right protocol, and store the linkage IDs (foreign keys into rpkid's database, basicly) in the IRDB. The irbe-setup.py program shows an example of how to do this. irdbd's default config file is irdbd.conf, start irdbd with "-c filename" to choose a different config file. All options are in the section "[irdbd]". Certificates, keys, and trust anchors may be in either DER or PEM format. Config file options: startup-message: String to log on startup, useful when debugging a collection of irdbd instances at once. sql-username: Username to hand to MySQL when connecting to irdbd's database. sql-database: MySQL's database name for irdbd's database. sql-password: Password to hand to MySQL when connecting to irdbd's database. cms-ta: Name of file containing CMS trust anchor to use when authenticating messages from rpkid. cms-key: Name of file containing RSA key to use when signing CMS messages to rpkid. cms-certs: Name(s) of file(s) containing certificate(s) to include in CMS wrapper when signing messages to rpkid. You can specify more than one certificate using OpenSSL-style subscripts: cms-certs.0, cms-certs.1, etc. https-key: Name of file containing RSA key to use in the HTTPS server role when listening for connections from rpkid. https-certs: Name(s) of file(s) containing certificate(s) to use in the HTTPS server role when listening for connections from rpkid. You can specify more than one certificate using OpenSSL-style subscripts: https-certs.0, https-certs.1, etc. https-url: Service URL for irdbd. Must be a https:// URL. ---------------------------------------------------------------- irbe-cli.py config file: The default config file is irbe.conf, start rpkid with "-c filename" to choose a different config file. All options are in the section "[irbe-cli]". Certificates, keys, and trust anchors may be in either DER or PEM format. Config file options: cms-ta: Name of file containing CMS trust anchor to use when authenticating messages from rpkid. cms-key: Name of file containing RSA key to use when signing CMS messages to rpkid. cms-certs: Name(s) of file(s) containing certificate(s) to include in CMS wrapper when signing messages to rpkid. You can specify more than one certificate using OpenSSL-style subscripts: cms-certs.0, cms-certs.1, etc. https-key: Name of file containing RSA key to use in the HTTPS client role when contacting rpkid. https-certs: Name(s) of file(s) containing certificate(s) to use in the HTTPS client role when contacting rpkid. You can specify more than one certificate using OpenSSL-style subscripts: https-certs.0, https-certs.1, etc. https-ta: Name of file containing trust anchor to use when verifying rpkid's HTTPS server certificate. https-url: Service URL for rpkid. Must be a https:// URL. ---------------------------------------------------------------- irbe-setup.py config file: The default config file is irbe.conf, start rpkid with "-c filename" to choose a different config file. Most options are in the section "[irbe-cli]", but a few are in the section "[irdbd]". Certificates, keys, and trust anchors may be in either DER or PEM format. Options in the "[irbe-cli] section: cms-ta: Name of file containing CMS trust anchor to use when authenticating messages from rpkid. cms-key: Name of file containing RSA key to use when signing CMS messages to rpkid. cms-certs: Name(s) of file(s) containing certificate(s) to include in CMS wrapper when signing messages to rpkid. You can specify more than one certificate using OpenSSL-style subscripts: cms-certs.0, cms-certs.1, etc. https-key: Name of file containing RSA key to use in the HTTPS client role when contacting rpkid. https-certs: Name(s) of file(s) containing certificate(s) to use in the HTTPS client role when contacting rpkid. You can specify more than one certificate using OpenSSL-style subscripts: https-certs.0, https-certs.1, etc. https-ta: Name of file containing trust anchor to use when verifying rpkid's HTTPS server certificate. https-url: Service URL for rpkid. Must be a https:// URL. Options in the "[irdbd] section: sql-username: Username to hand to MySQL when connecting to irdbd's database. sql-database: MySQL's database name for irdbd's database. sql-password: Password to hand to MySQL when connecting to irdbd's database. ---------------------------------------------------------------- cronjob.py config file: The default config file is cronjob.conf, start cronjob with "-c filename" to choose a different config file. All options are in the section "[cronjob]". Certificates, keys, and trust anchors may be in either DER or PEM format. Config file options: https-key: Name of file containing RSA key to use in the HTTPS client role when contacting rpkid. https-certs: Name(s) of file(s) containing certificate(s) to use in the HTTPS client role when contacting rpkid. You can specify more than one certificate using OpenSSL-style subscripts: https-certs.0, https-certs.1, etc. https-ta: Name of file containing trust anchor to use when verifying rpkid's HTTPS server certificate. https-url: Service URL for rpkid. Must be a https:// URL. ---------------------------------------------------------------- testbed.py ---------------------------------------------------------------- testpoke.py