eccert

4 minute readAutomation

A command-line tool used to manage the CloudBees CD/RO Certificate Authority (CA) and the certificates configured in CloudBees CD/RO Server and CloudBees CD/RO Agent installations.

Do not use eccert as sudo, which would change the ownership of the configuration files (such as the keystore file) to the root user. These files must be owned by the user who starts the CloudBees CD/RO services.

Usage

eccert [ options ] command [ arg …​ ]

Commands

addTrustedServer crt

Add a server CA certificate to the agent’s keystore.

getCRL

Retrieve the contents of the current certificate revocation list.

initAgent [ --local | --remote ] [ options ]

Initialize the agent keystore with a new public/private key pair. Generates the agent certificate signing request. If run on the server host, the certificate will automatically be signed by the server CA, and the CA certificate and the signed agent certificate are installed in the agent’s keystore. If run on a non-server host, the signing request is left in the agent directory. If CA Cert is provided, the CA certificate is installed in the agent’s keystore.

--local

Use the local server CA to sign the agent certificate.

--remote

Connect to a remote CloudBees CD/RO server to sign the agent certificate.

--force

Replace any existing keystore.

--cname name

Use the specified name as the common name (CN) in the agent certificate subject. This is normally the fully qualified domain name used by clients to connect to the agent.

--altNames entries

Use the specified list of entries (comma or space separated) as the subjectAlternateNames list in the agent certificate. Simple names are interpreted as dns entries. Entries may begin with "dns:" or "ip:" to indicate the type (for example, ` "ip:192.168.0.1"` or "dns:myHost" ). If no entries are specified, then reverse DNS is used to look up the registered names of the host’s IP addresses.

initCA

Initialize the server CA. Creates a new CA key and certificate.

initServer [ options ]

Initialize the server keystore. Creates and signs the server certificate. Installs the CA certificate and the signed server certificate into the server’s keystore.

--force

Replace any existing keystore.

--cname name

Use the specified name as the common name (CN) in the server certificate subject. This is normally the fully qualified domain name used by clients to connect to the server.

--altNames entries

Use the specified list of entries (comma or space separated) as the subjectAlternateNames list in the server certificate. Simple names are interpreted as dns entries. Entries may begin with "dns:" or "ip:" to indicate the type (for example, "ip:192.168.0.1" or "dns:myHost" ). If no entries are specified, then reverse DNS is used to look up the registered names of the host’s IP addresses.

list [ --agent | --server | --index [ --verbose ]

Display certificate information for agent and/or server keystores or the CA certificate index. If no options are specified, both the agent and server keystores are listed.

--agent

List the contents of the agent keystore.

--server

List the contents of the server keystore.

--index

List the contents of the CA issued certificates index.

--verbose

Display additional details.

refreshCRL

Refresh the certificate revocation list from the CloudBees CD/RO server.

revoke index

Revoke a previously issued certificate by index.

signCertificate csr crt

Sign the certificate signing request provided in file csr and write the signed result to the file crt. The request is rejected by the CA if there is a matching certificate already in the CA database.

updateAgentCertificate crt

Install a previously signed certificate crt into the agent’s keystore.

Server communication options

--server host

Address of the CloudBees CD/RO server. Defaults to the value of the COMMANDER_SERVER environment variable. If that does not exist, it defaults to localhost.

--securePort port

HTTPS listener port on the server. Defaults to 8443.

Global options

--help

Print the Help message.

--version

Print the version message.

Examples

Configure an agent to talk to any server (untrusted mode)

This example generates a new self-signed certificate for the agent and recreates the keystore with no trusted authorities.

    $ eccert initAgent -force
    Generating keys
    Generating certificate request
        cname=<myAgent.example.com>
        san=<dns:myAgent.example.com>
Configure an agent to accept connections only from a single remote CloudBees CD/RO server

This example generates a new certificate for the agent that is signed by the remove server’s certificate authority and installs the signed certificate and its associated trust chain in the agent’s keystore. After this point, the agent will only accept requests from the specified server and will be used as a trusted resource by the server.

    $ ectool --server myserver login admin pw
    $ eccert --server myserver initAgent -remote
    Generating certificate request
        cname=<myAgent.example.com>
        san=<dns:myAgent.example.com>
    Asking server 'myserver' to sign certificate
    Importing 'CA:myserver.example.com' certificate
    Importing 'jetty' certificate
Configure a CloudBees CD/RO server with additional host names in the certificate

This example regenerates the CloudBees CD/RO Server Certificate, the specified common name, and alternate subject names to allow trusted connections with multiple external dns names.

    $ eccert initServer --force --cname "myServer.example.com" --altNames "myServer,server2.example.com"
    Generating keys
    Generating certificate request
        cname=<myserver.example.com>
        san=<dns:myserver,dns:server2.example.com>
    Signing server certificate
    Importing 'CA:myserver.example.com' certificate
    Importing 'jetty' certificate