CERTMONGER(8)

📦 version 0.79.21, in alpine 3.24, centos-stream 10, centos-stream 9, debian bookworm, debian trixie, fedora 43, fedora 44, opensuse-leap 16.0, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ NAME ✨

dogtag-ipa-renew-agent-submit — and bestie, heads up, this whole page is from the CERTMONGER(8) manual, aka the System Manager's Manual. That's the vibe. 💅

🎀 SYNOPSIS 🎀

dogtag-ipa-renew-agent-submit [options] [csrfile]

🦋 DESCRIPTION 🦋

okay so dogtag-ipa-renew-agent-submit is the little helper bestie that certmonger calls up whenever it needs to make certificate renewal requests to Dogtag instances running on IPA servers. It is not normally run interactively, but lowkey you can run it yourself if you're troubleshooting. no cap. 🔍

The preferred move is to ask for a renewal of an already-issued certificate, using its serial number. Where does that serial number come from? Either it's read from a PEM-formatted certificate handed to you in the CERTMONGER_CERTIFICATE environment variable, or you pass it on the command line with the -s or -D option. If no serial number shows up anywhere, then the client will try to get a brand new certificate by submitting a signing request to the CA. iconic behavior honestly. ✨

The signing request that's gonna get submitted should either live in a file whose name you give as an argument, or be fed into dogtag-ipa-renew-agent-submit via stdin. pick your fighter. 🫶

certmonger does not yet support retrieving trust information from Dogtag CAs. that's just the tea, bestie. 😭

💖 OPTIONS 💖

  • -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. 🫶
  • -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. 🗣️

🔐 AGENT KEY AND CERTIFICATE OPTIONS 🔐

okay so this whole little cluster is about where the private key and public certificate live — the ones the client should use to authenticate to the CA's agent interface. and bestie, which values you actually use depends on which cryptography library your copy of libcurl was linked with. that's just how it is. 🦋

The location of the certificate used for authentication to the CA needs to be provided in either a combination of PEM files using --certfile and --keyfile or an NSS database using --dbdir and --nickname. The default for --cafile is /etc/ipa/ca.crt. 🎀

  • -d dbdir, --dbdir=dbdir — Use an NSS database in the specified directory for this certificate and key. Only valid with -n. 🗂️
  • -n NAME, --nickname=NAME — Use the NSS key with this nickname. Only valid with -d. 🏷️
  • -c FILE, --certfile=FILE — The PEM file that contains the public certificate. Only valid with -k. 📄
  • -k FILE, --keyfile=FILE — The PEM file that contains the private certificate. Only valid with -c. 🔑
  • -p FILE, --sslpinfile=FILE — The name of a file which contains a PIN/password which will be needed in order to make use of the agent credentials. 📌
  • -P PIN, --sslpin=PIN — The name of a file which contains a PIN/password which will be needed in order to make use of the agent credentials. 📌

…and there's more, bestie, keep scrolling 👀💖

✨ EXIT STATUS ✨

ok so like, the exit code is literally the whole mood of the operation 💅 here's what each one is telling you:

  • 0 — slay!! the certificate was issued 🎉 and bestie, it will be printed for you.
  • 1 — the CA is still thinking 🤔 (yes, thinking, iconic of it). a cookie (state) value will be printed so you can come back later.
  • 2 — the CA rejected the request 💀 an error message may be printed.
  • 3 — the CA was unreachable 😭 an error message may be printed.
  • 4 — critical configuration information is missing 🙈 an error message may be printed.
  • 5 — the CA is still thinking. again. a suggested poll delay (specified in seconds) and a cookie (state) value will be printed 🍓
  • 17 — the CA indicates that the client needs to attempt enrollment using a new key pair 👑 like okay glow-up era, new keys it is.
lowkey important: those "still thinking" codes are not errors fr fr, they're just the CA taking its sweet time. read the cookie, wait, try again 🫶

🎀 FILES 🎀

  • /etc/ipa/default.conf — this is the IPA client configuration file. it gets consulted to determine the URL for the Dogtag server's end-entity and agent interfaces, but only if they weren't supplied as arguments. iykyk ✨

🦋 BUGS 🦋

found a bug? no cap, please file tickets for any that you find at https://fedorahosted.org/certmonger/ — the maintainers wanna know 💜

🌈 SEE ALSO 🌈

go off, read the whole squad:

and that's the page bestie!! this was the certmonger Manual, section 8, dated October 27, 2015 🫶 go get those certs, you're the main character of your own PKI 💖✨

📦 where this page comes from