Add pkispawn EST deployment documentation #4866
Conversation
There was a problem hiding this comment.
Please see my comments below. My main concern is that sometimes we introduce a new information (e.g. estUser) without explaining how to set it up, so it might be difficult for users to follow, but if you prefer we can address that in a separate PR later. Or if the doc still requires a lot of development, we can write it in the wiki first, then when it's ready we can just import it into the source repository.
|
|
||
| Overview | ||
| -------- | ||
| ## Overview | ||
|
|
||
| This page describes the process to install a *EST subsystem*. |
There was a problem hiding this comment.
I'd suggest changing this to an EST.
There was a problem hiding this comment.
@edewata did you just mean to correct the 'a' before "EST subsystem" (so it reads "an EST subsystem"), or did you mean to correct the 'a' AND suggest to remove the word "subsystem" too (so it reads "an EST")? I think we have called other subsystems with the word "subsystem" at many places.
There was a problem hiding this comment.
Yes, I meant an EST subsystem.
| EST Subsystem Installation | ||
| -------------------------- | ||
| Install the *EST subsystem* via dnf command. | ||
| Finally, install the *EST subsystem* via dnf command. | ||
|
|
||
| ``` | ||
| # dnf install dogtag-pki-est |
There was a problem hiding this comment.
Generally package installations should be done first before creating/configuring the instances since these tasks might be done by different people with different roles.
There was a problem hiding this comment.
The operation above are not related to the EST instance itself but to the CA. In any case I moved this before so it will be the first operation.
|
|
||
| This page describes the process to install a *EST subsystem*. | ||
|
|
||
|
|
||
| Prerequisite | ||
| -------------------------- | ||
| ## Prerequisite |
There was a problem hiding this comment.
There's an issue with the commands in this section. There's no instruction how to set up the NSS database in nssdb folder. Should we just use the default NSS database in ~/.dogtag/nssdb and remove the -d nssdb -c 4me2Test from the doc?
| # EST installation using `pki-server` | ||
|
|
||
| After the prerequisite in [Installing | ||
| EST](Installing_EST.md), it is possible to installa **EST**. |
| ``` | ||
| # cat >/var/lib/pki/pki-tomcat/conf/est/backend.conf <<EOF | ||
| class=org.dogtagpki.est.DogtagRABackend | ||
| url=https://$(hostname):8443 |
There was a problem hiding this comment.
The $(hostname) might be confusing since IIUC we do not support command substitution like in shells, so I'd suggest to use something like <hostname> which indicates that it needs to be replaced with a real hostname, or just put a sample hostname (e.g. ca.example.com).
There was a problem hiding this comment.
Actually this is a cat command and not the file so there is shell substitution so it is possible to cut&paste. If I change with <hostname> then it need to be edited.
| ## REALM user DB | ||
|
|
||
|
|
||
| **EST** subsystem has its own realm authtnetication with a separate |
| $ pkispawn \ | ||
| -f /usr/share/pki/server/examples/installation/est.cfg \ | ||
| -s EST \ | ||
| -D est_realm_url=ldap://ds.example.com:3389 \ |
There was a problem hiding this comment.
Should this be estds.example.com?
| To remove the EST subsystem it is possible to use the `pkidestroy` command as follow: | ||
|
|
||
| ``` | ||
| pkidestroy -i pki-tomcat -s CA -v |
There was a problem hiding this comment.
Should this be pkidestroy -s EST? The -i and -v are optional, but it's ok to include.
There was a problem hiding this comment.
the -v is in all commands. I am removing the -i
| -D est_ca_user_certificate=estUser \ | ||
| -D pki_server_pkcs12_path=$SHARED/est_server.p12 \ | ||
| -D pki_server_pkcs12_password=Secret.123 \ |
There was a problem hiding this comment.
We probably should explain how to create the estUser and est_server.p12, maybe in a separate section or a separate doc. The $SHARED should not be included since it's only available in the CI.
There was a problem hiding this comment.
I am adding a note but if it is not clear then it is better to move and add just a link
| -D pki_cert_chain_path=ca_signing.crt \ | ||
| -D pki_cert_chain_nickname=caSigning \ |
There was a problem hiding this comment.
We probably should explain how to get the ca_signing.crt.
|
|
||
| This page describes the process to install a *EST subsystem*. | ||
|
|
||
|
|
||
| Prerequisite | ||
| -------------------------- | ||
| ## Prerequisite | ||
|
|
||
| Create a Dogtag user group for EST RA accounts (**EST RA Agents**), and an EST RA |
There was a problem hiding this comment.
To avoid confusion, I'd start with "On the CA," so it reads "On the CA, create a Dogtag user group for the EST RA accounts ..."
There was a problem hiding this comment.
Also, for the pki commands below, it's best not to assume the defaults on user's command line, because if they happen to use something different, it might frustrate them to have to dig up the information on their own. Perhaps add a note at the top that says something like "The commands below assumes that the default host and port number of the CA are the local host and 8443 (correct me if I'm wrong). To specify a different host and port number, use -h and -p respectively. It is also assumed that the nssdb is under ~/.dogtag/nssdb (to reflect @edewata 's suggestion above). To specify a different nssdb path, use -d"
There was a problem hiding this comment.
Also (sorry I can't seem to add comment to the exact line below) for the EST profile, estServerCert.cfg already exists in the CA, so we just need to enable it (maybe with some edits, such as AIA), isn't it?
There was a problem hiding this comment.
@ladycfu I think you are right although in all the tests I have done I always add the profile and do not get any warning like "The profile already exist!". I'll remove the add and double check with the CI.
There was a problem hiding this comment.
@ladycfu I did a test and it is not included in the default profile available with the CA so it need to be added explicitly. At least using the master branch and I think it should be the same for other branches so I am leaving this step.
| password=est4ever | ||
| EOF | ||
| ``` | ||
| There are two options for the installation: |
There was a problem hiding this comment.
Is there any advantage to pki-server that we want to continue providing it as an option?
There was a problem hiding this comment.
In general the pki-server tool provides more control over the installation process (i.e. fine-grained installation). If something fails, it can be fixed immediately, then the installation can resume from that point. With pkispawn it's all or nothing. pkispawn does many things at once so all params must be set correctly at the beginning. If something fails, usually you'd have to clean up the environment and start over from the beginning. This could be problematic if pkispawn leaves many orphan keys in HSM or starts replicating a huge database.
There was a problem hiding this comment.
Also for containers we don't want to do everything that pkispawn does, so pki-server tool provides a mechanism to do what's needed for containers.
I think for the primary EST doc we could suggest users to use pkispawn, but we should keep the EST doc using pki-server if they need more control over the installation process.
There was a problem hiding this comment.
@edewata Thanks for the clarification. Yes I think we should keep both options available, but perhaps add the explanation to help with choices?
There was a problem hiding this comment.
I was thinking the main EST install doc should just use pkispawn, but we also provide a link that says something like "Manual EST Installation" or "Advanced EST Installation" to another doc using pki-server. We can include the above explanation in that other doc. This way the user won't be forced to read, understand the differences, then make a choice before they can start the installation, but they can try pkispawn with the sample config files first (which is what most people want to do initially), then if it's not enough they can try pki-server. What do you think?
|
|
||
|
|
||
| **EST** subsystem has its own realm authtnetication with a separate | ||
| user DB. Out of the box *LDAP*, *PostreSQL* and file based DB are |
There was a problem hiding this comment.
I jumped directly from "Using pkispawn here", I don't see any mention for an ldap instance to be created. Did I miss a step in the jump?
There was a problem hiding this comment.
It is in the subsection. Should I move it?
There was a problem hiding this comment.
@fmarco76 which subsection?
There was a problem hiding this comment.
I was thinking the one below from line 14. But reading again your comment maybe you want the DS installation steps, not just the how the ldap tree should be populated. Should I include the step to create the instance? (And the same for postegresql?)
There was a problem hiding this comment.
before you can do line 14 and on, you want to mention that a DS instance needs to be created. I think there already is a page for that which you can link to. See an example from the 2nd paragraph of Overview here : https://github.com/dogtagpki/pki/blob/master/docs/installation/ca/Installing_CA.md
| provided in order to retrieve the user information from the DB. | ||
|
|
||
|
|
||
| ## Installation |
There was a problem hiding this comment.
Is this section supposed to be for installing on the same instance, or does it contain something that shared with the installation on separate instance? It is currently one level above ### Installation on separate instance.
There was a problem hiding this comment.
The content of this section applies to both cases: same or separate instance. However, in the second case there are a couple of additional steps to get the CA and SSL certificates.
| pki-server cert-export ca_signing --cert-file ca_signing.crt | ||
| ``` | ||
|
|
||
| EST will get the SSL server certificate through the EST provided user |
There was a problem hiding this comment.
I'm reading this comment a few times and have to make a guess. Please verify my understanding. This paragraph is saying that without the two pkcs12 related parameters, pkispawn will get the EST's server cert automatically issued by using the estServerCert (the default name, which is hard-coded?) profile. And if one wishes to use a pre-generated server cert/keys, then supply its p12 and passwd as stated in the pkcs12 params.
There was a problem hiding this comment.
@ladycfu your guess is correct. If it is not provided with a p12 then it will try to get a certificate using the EST credentials and profile which are not hard-coded but they are parameter (est_ca_profile and est_ca_user_*). Currently we do not support multiple profiles although the specification allows to include a label in a request which could be used to select different CAs (or profiles I think).
There was a problem hiding this comment.
@fmarco76 got it! In that case, I suggest a little clarification. Maybe something like "By default, the EST server cert will be issued based on the information provided via the pkispawn parameters est_ca_profile and est_ca_user_. Alternatively, the EST server cert could be pre-issued prior to pkispawn with its full chain in PKCS#12 bundle supplied via the pki_server_pkcs12_ parameters on the pkispawn command line as exemplified below. It is important tha tthe certificate aliases ..."
fmarco76
force-pushed
the
EST_doc
branch
2 times, most recently
from
6c8d214 to
98cf1e5
Compare
| -D est_realm_url=ldap://estds.example.com:3389 \ | ||
| -D pki_ca_uri=https://ca.example.com:8443 \ | ||
| -D est_ca_user_password= \ | ||
| -D est_ca_user_certificate=estUser \ |
There was a problem hiding this comment.
@fmarco76 looks like you updated while I was typing up the following: Just realized that I missed the "(and the user certificate if it is needed to connect to the CA)" part in my suggestion clarification. So the est_ca_user_* are for client cert talking to the CA then? Which profile is it using (which parameter in pkispawn cfg?)? As for it's alternative, I see in the example below, est_ca_user_password and est_ca_user_certificate are supplied, but it doesn't seem to point to any p12. How does it work?
There was a problem hiding this comment.
So the est_ca_user_* are for client cert talking to the CA then?
These parameter are to configure the CA user for EST communication. This is created in the prerequisite described in the main installation document and added here.
Which profile is it using (which parameter in pkispawn cfg?)
The profile is defined with the option est_ca_profile (line 107) and default it is estServiceCert.
As for it's alternative, I see in the example below, est_ca_user_password and est_ca_user_certificate are supplied, but it doesn't seem to point to any p12. How does it work?
est_ca_user_certificate is the name of the certificate to use inside the nssdb of the instance. est_ca_user_password is empty to be sure it is not used but if both are provided I think the certificate has precedence but it is in the EST code so I should verify.
There was a problem hiding this comment.
@fmarco76 sorry I'm still a bit lost. Sounds like you are saying that the EST server cert and the EST client cert (the one to be associated with the est user in the CA agent group) are using the same enrollment profile (I hope not), estServerCert? Oh wait, you said estServiceCert. So there are two profiles, one being estServerCert (the one for server) and the other being estServiceCert (the one for client)? I could see how the EST server cert is being issued, either via the default set in est_ca_profile=, or by pkispawn command line -D pki_server_pkcs12_*, but I still don't get how the EST client cert (for talking to the ca) got issued. Unless I missed it, I do not see it being instructed to be issued in the prerequisite section. Could you please point to me where that is?
|
|
|
||
| ``` | ||
| # pki -d nssdb -c 4me2Test -n caadmin ca-profile-add --raw estServerCert.cfg | ||
| # pki -n caadmin ca-profile-add --raw estServerCert.cfg |
There was a problem hiding this comment.
this says "estServerCert.cfg"
|
|
||
| ``` | ||
| # pki -d nssdb -c 4me2Test -n caadmin ca-profile-add --raw estServerCert.cfg | ||
| # pki -n caadmin ca-profile-add --raw estServerCert.cfg | ||
| ---------------------------- | ||
| Added profile estServiceCert | ||
| ---------------------------- |
There was a problem hiding this comment.
and this is estServiceCert". So that's two profiles?
fmarco76
force-pushed
the
EST_doc
branch
3 times, most recently
from
4bc8691 to
081381e
Compare
There was a problem hiding this comment.
I'm actually not finished with my review. I am stopping midway because I find it not easy to make documentation change requests and comments in a PR. I think it'll be easier to do that in a google doc. @fmarco76 is it possible that you create a gdoc for this purpose? Thanks!
| account (**est-ra-1**). The EST subsystem will use this account to authenticate to | ||
| the CA subsystem and issue certificates on behalf of EST clients. | ||
|
|
||
| Note: the commands below assumes that the CA is running in the same host on |
There was a problem hiding this comment.
The commands below assume that the CA is running on the same host ...
|
|
||
| Note: the commands below assumes that the CA is running in the same host on | ||
| the default port and the nssdb is located in `~/.dogtag/nssdb`. To | ||
| point to a CA in a different host or with a different port use the options `-h |
There was a problem hiding this comment.
... point to a CA on a different host ...
| User: est-ra-1 | ||
| ``` | ||
|
|
||
| Add and enable the EST profile `estServiceCert.cfg` (it is available in `/usr/share/pki/ca/profiles/ca` if the *dogtag-pki-ca* package is installed): |
There was a problem hiding this comment.
(cfu) Since this is the first time you mention the word "profile", let's add the word "enrollment" to make it more clear to the reader what a "profile" is.
Add and enable the EST enrollment profile ...
| -------------------------------- | ||
| ``` | ||
|
|
||
| Note: before enable the profile verify if the options satisfy the requirement for the deployment. |
There was a problem hiding this comment.
Note: before enabling the profile verify the content to see if the options satisfy the requirement for your deployment.
|
|
||
| Before adding users, please ensure that you have configured the | ||
| directory server and added base entries. The step is described | ||
| https://github.com/dogtagpki/pki/wiki/DS-Installation[here]. |
There was a problem hiding this comment.
Note: I have split the DS-Installation page and moved it to the master branch under https://github.com/dogtagpki/pki/tree/master/docs/installation/others . You could leave this link as is for now until we have finalized the moves (still work in progress).
|
|
||
| The user DB requires a node containing the users (_inetOrgPerson_) and | ||
| a node containing the groups (_groupOfUniqueNames_). Therefore, if | ||
| the base dn is like `dc=pki,dc=example,dc=com` it is possible create a |
There was a problem hiding this comment.
... it is possible to create a ...
|
|
||
| First, prepare a database (e.g. est) and a user (e.g. est) to access | ||
| the database. Verify the database connection with the following | ||
| command: |
There was a problem hiding this comment.
I'm not familiar with PostgreSQL, but when you say "Verify the database connection with the following command:", which command are you referring to? I'm asking because the next paragraph seems to be talking about creating user tables that states " ... The tables can be created with the command:" followed by a command. Are they both talking about the same command, or is there supposed to be another command right after the first paragraph?
|
|
||
| == Installation == | ||
|
|
||
| An example installation configuration is provided in |
There was a problem hiding this comment.
(cfu) just to make it clear that the cfg file is for pkispawn:
An example pkispawn installation configuration is provided in
|
The documentation is updated to match the configuration in the new CI workflow for EST using
pkispawn.Almost all operation are performed by pkispawn but the user and profile for EST need to be created in advance.