dogtag-ipa-renew-agent-submit
dogtag-ipa-renew-agent-submit [options] [csrfile]
dogtag-ipa-renew-agent-submit is the helper which
certmonger uses to make certificate renewal requests to Dogtag
instances running on IPA servers. It is not normally run interactively, but
it can be for troubleshooting purposes.
The preferred option is to request a renewal of an already-issued
certificate, using its serial number, which can be read from a PEM-formatted
certificate provided in the CERTMONGER_CERTIFICATE environment
variable, or via the -s or -D option on the command line. If
no serial number is provided, then the client will attempt to obtain a new
certificate by submitting a signing request to the CA.
The signing request which is to be submitted should either be in a
file whose name is given as an argument, or fed into
dogtag-ipa-renew-agent-submit via stdin.
certmonger does not yet support retrieving trust
information from Dogtag CAs.
- -E EE-URL,
--ee-url=EE-URL
- The top-level URL for the end-entity interface provided by the CA. In IPA
installations, this is typically
http://SERVER:EEPORT/ca/ee/ca. If no
URL is specified, the host named in the [global] section in
the /etc/ipa/default.conf file is used as the value of
SERVER, and the value of EEPORT will be inferred based on
the value of the dogtag_version in the [global] section in
the /etc/ipa/default.conf file: if dogtag_version is set to
10 or more, EEPORT will be set to 8080. Otherwise it will be
9180.
- -A AGENT-URL,
--agent-url=AGENT-URL
- The top-level URL for the agent interface provided by the CA. In IPA
installations, this is typically
https://SERVER:AGENTPORT/ca/agent/ca.
If no URL is specified, the host named in the [global]
section in the /etc/ipa/default.conf file is used as the value of
SERVER, and the value of AGENTPORT will be inferred based on
the value of the dogtag_version in the [global] section in
the /etc/ipa/default.conf file: if dogtag_version is set to
10 or more, AGENTPORT will be set to 8443. Otherwise it will
be 9443.
- -i FILE,
--cafile=PATH
- The location of a file containing a copy of the CA's certificate, against
which the CA server's certificate will be verified. The default is
/etc/ipa/ca.crt.
- -C DIR,
--capath=DIR
- The location of a directory containing a copy of the CA's certificate,
against which the CA server's certificate will be verified.
- -d DIR,
--dbdir=DIR
- The NSS database that contains credentials to authenticate to the CA.
- -n NAME,
--nickname=NAME
- The nickname of the certificate used for authentication.
- -c FILENAME,
--certfile=FILENAME
- The certificate in PEM format used for authentication.
- -k FILENAME,
--keyfile=FILENAME
- The private key for the certificate in PEM format used for authentication.
It may be encrypted.
- -p FILENAME,
--sslpinfile=FILENAME
- A file that contains the pin for the private key file or NSS
database.
- -P STRING,
--sslpin=STRING
- The pin for the private key file or NSS database.
- -s NUMBER,
--hex-serial=NUMBER
- The serial number of an already-issued certificate for which the client
should attempt to obtain a new certificate, in hexidecimal form, if one
can not be read from the CERTMONGER_CERTIFICATE environment
variable.
- -D NUMBER,
--serial=NUMBER
- The serial number of an already-issued certificate for which the client
should attempt to obtain a new certificate, in decimal form, if one can
not be read from the CERTMONGER_CERTIFICATE environment
variable.
- -S STATE-VALUE,
--state=STATE-VALUE
- A cookie value provided by a previous instance of this helper, if the
helper is being asked to continue a multi-step enrollment process. If the
CERTMONGER_COOKIE environment variable is set, its value is
used.
- -T NAME,
--profile=NAME
- The name of the type of certificate which the client should request from
the CA if it is not renewing a certificate (per the -s option
above). If the CERTMONGER_CA_PROFILE environment variable is set,
its value is used. Otherwise, the default value is
caServerCert.
- -t,
--profile-list
- Instead of attempting to obtain a new certificate, query the server for a
list of the enabled enrollment profiles.
- -O param=value,
--approval-option=param=value
- An additional parameter to pass to the server when approving the signing
request using the agent's credentials. By default, any server-supplied
default settings are applied. This option can be used either to override a
server-supplied default setting, or to supply one which would otherwise
have not been used.
- -N,
--force-new
- Even if an already-issued certificate is available in the
CERTMONGER_CERTIFICATE environment variable, or a serial number has
been provided, don't attempt to renew a certificate using its serial
number. Instead, attempt to obtain a new certificate using the signing
request. The default behavior is to request a renewal if possible.
- -R,
--force-renew
- Negates the effect of the -N flag.
- -o param=value,
--submit-option=param=value
- When initially submitting a request to the CA, add the specified parameter
and value along with any request parameters which would otherwise be sent.
This option is not typically used.
- -a,
--agent-submit
- Use agent credentials, specified using some combination of the -d,
-n, -c, and -k flags, to authenticate to the CA when
initially submitting a request to the CA or retrieving the list of enabled
enrollment profiles. This is typically required when the enrollment
profile being used uses AgentCertAuth-based authentication, and
requires that the URL specified using the -E flag be an HTTPS URL,
or when the URL specified using the -E flag is an HTTPS URL.
- -u username,
--uid=username
- When initially submitting a request to the CA, supply the specified value
as a user name. This is typically required when the enrollment profile
being used uses UidPwdDirAuth-based or NISAuth-based
authentication..TP -U userdn, --upn=userdn
When initially submitting a request to the CA, supply the specified value
as the DN (distinguished name) of the user's entry in a directory server
which the CA is configured to use for checking the user's password. This
is typically required when the enrollment profile being used uses
UdnPwdDirAuth-based authentication.
- -W PASSWORD,
--userpwd=PASSWORD
- When initially submitting a request to the CA, supply the specified value
as the password for the user whose name is specified with the -u
option, or whose DN is specified with the -U option. This is
typically only required when the enrollment profile being used uses
UidPwdDirAuth-based, UserPwdDirAuth-based, or
NISAuth-based authentication. If the URL specified using the
-E flag is not an HTTPS URL, this value will not be encrypted.
- -w FILE,
--userpwdfile=FILE
- When initially submitting a request to the CA, read from the specified
file a password to supply for the user whose name is specified with the
-u option, or whose DN is specified with the -U option. This
is typically only required when the enrollment profile being used uses
UidPwdDirAuth-based, UserPwdDirAuth-based, or
NISAuth-based authentication. If the URL specified using the
-E flag is not an HTTPS URL, this value will not be encrypted.
- -Y PIN,
--userpin=PIN
- When initially submitting a request to the CA, supply the specified value
as the PIN for the user whose name is specified with the -u option,
or whose DN is specified with the -U option. This is typically only
required when the enrollment profile being used uses
UidPwdPinDirAuth-based authentication. If the URL specified using
the -E flag is not an HTTPS URL, this value will not be encrypted.
-y FILE, --userpinfile=FILE When initially
submitting a request to the CA, read from the specified file a PIN to
supply for the user whose name is specified with the -u option, or
whose DN is specified with the -U option. This is typically only
required when the enrollment profile being used uses
UidPwdPinDirAuth-based authentication. If the URL specified using
the -E flag is not an HTTPS URL, this value will not be
encrypted.
- -v, --verbose
- Increases the logging level. Use twice for more logging. This option is
mainly useful for troubleshooting.
- 0
- if the certificate was issued. The certificate will be printed.
- 1
- if the CA is still thinking. A cookie (state) value will be printed.
- 2
- if the CA rejected the request. An error message may be printed.
- 3
- if the CA was unreachable. An error message may be printed.
- 4
- if critical configuration information is missing. An error message may be
printed.
- 5
- if the CA is still thinking. A suggested poll delay (specified in seconds)
and a cookie (state) value will be printed.
- 17
- if the CA indicates that the client needs to attempt enrollment using a
new key pair.
- /etc/ipa/default.conf
- is the IPA client configuration file. This file is consulted to determine
the URL for the Dogtag server's end-entity and agent interfaces if they
are not supplied as arguments.
Please file tickets for any that you find at
https://fedorahosted.org/certmonger/