Note: This web site is only kept up to date for OSG Software 1.2 (VDT 2.0.0). If you are looking for information for the most recent release, the RPM-based OSG Software 3.0, please see the OSG documentation web site

NAME

vdt-ca-manage - Manage the VDT CA certificate installation

SYNOPSIS

    vdt-ca-manage [global_options] command 

    global_options =
        [--vdt-location <location>]
        [--verbose]
        [--force]
        [--cert-dir <location>]
        [--help | --usage]
        [--version]
        [--auto-refresh]

    command = [manage_command | status_command] 

    status_command = [
        showCAURL |
        listCA [--pattern <pattern>] |
        verify [--hash <CA hash> | --pattern <pattern>] |
        diffCAPackage |
        show [--certfile <cert_file> | --hash <CA hash>] |
        showChain [--certfile <cert_file> | --hash <CA hash>]
    ]

    manage_command = [
        setupCA [--location <root|local|PATH> --url <osg|osg-new|igtf-old|igtf-new|itb|itb-new|itb-igtf-old|itb-igtf-new|vdt|URL>] [--no-update] [--force]|
        refreshCA |
        fetchCRL |
        setCAURL [--url <osg|osg-new|igtf-old|igtf-new|itb|itb-new|itb-igtf-old|itb-igtf-new|vdt|URL>] |
        add [--dir <local_dir>] --hash <CA hash> |
        remove --hash <CA hash>
    ]

DESCRIPTION

This tool provides a unified interface to manage the VDT CA Certificate installations. It provides status commands that allows you to list the CAs and the validity of the CAs and CRLs included in the installation. The manage commands allow you to fetch CAs and CRLs, change the distribution URL, as well as add and remove CAs from your local installation.

OPTIONS

--vdt-location <location>: The location the VDT was installed in. This option overrides the $VDT_LOCATION environment variable if it exists. This option is not needed if $VDT_LOCATION is set to the correct location.
--verbose: Provides you with more information depending on the command context.
--force: Forces the command to run ignoring any checks/warnings. The actual effect is context dependent, and this behavior is noted in the command details below.
--cert-dir <location>: This location specifies the path CA directory. If this option is not specified then the command will look for $X509_CERT_DIR, and $VDT_LOCATION/globus/TRUSTED_CA respectively. If none of these directories can be found, the command will exit with an error.
--auto-refresh: This option will indicate if it is permissible to fetch CAs and CRLs as deemed necessary by this tool. For example at the end of an addCA/removeCA it would be advisable to refresh the CA list and the corresponding CRLs. The default is not to refresh.
--version: Prints the version of the vdt-ca-certs-manager tool.
--help: Print usage information. Show a brief explanatory text for using vdt-ca-certs-manager.

STATUS_COMMANDS

showCAURL: This will print out the distribution location specified in the config file. This command will read vdt-update-certs.conf and output cacerts_url.
listCA [--pattern <pattern>]: This command will use openssl x509 command on the files in the --dir to provide hash, the subject, the issuer and whether a CA is IGTF or TeraGrid accredited and distribution package are used to download CAs into the directory. --verbose option will provide additional information including all associated dates (CA cert issuance date, and CRL issuance date, and expiry dates). The command will look for CA files in the -cert-dir. The <pattern> specified in the option will be matched, using perl regex, against the subject/issuer field of the certificate and all CAs are listed if no pattern is given.
verify [--hash <CA hash> | --pattern <pattern>]: The verify command will check all CAs (or if specified only the <CA hash> or CAs that match the <pattern>) in the <cert-dir> directory, to see if any CA/CRL have expired or are about to do so. If any expired CA/CRL are found, an error is issued along with the hash of the CA. A warning is issued if either the CA cert or CRL is about the expire within the next 24 Hrs. The --verbose option provides the CA Name, date the CA certs and CRL files are issued, and when they will expire.
diffCAPackage: It compare the hash of certificates included in the certificate directory against the latest VDT/OSG/ITB distribution (based on your cacerts_url) and outputs the difference.
show [--certfile <cert_file> | --hash <CA hash>]: This command will essentially provide a condensed output of openssl x509 command. It takes in a certificate or proxy file or an hash as input. --verbose option will provide the full text output of openssl command. If --hash option is used we will look for the <CA hash>.0 file in the <cert-dir>.
showChain [--certfile <cert_file> | --hash <CA hash>]: This command will output the trust chain of the certificate or proxy. <cert-dir> will be used as the directory in which search for ancestor certs will be conducted.

UPDATE_COMMANDS

setupCA: This command is used for the inital setup of the CA package. The CA package can be setup to download CAs from any URL. Keywords are provided for the VDT, OSG, and ITB distributions. For the location to specify, keywords are provided to install into 'root' (/etc/grid-security) or 'local' (VDT_LOCATION/globus/share). A --no-update option is available. Setting this flag instructs just setup the symlinks only and not to run configure vdt-update-certs to be run automatically. This option is for installations that will not manage their own certificates, but will rely on updates through another method (such as RPM, or using vdt-update-certs from a different VDT installation). A common use case for this is to have worker-node installations rely on the CA certificates being available on an NFS share, and the updating will happen on a single node.
refreshCA: This command run vdt-update-certs to check for a new version of the CA distribution. If you already have the latest version, but wish to force an update anyways, use the --force option.
fetchCRL: It retrieves CRLs for all CAs within the directory. This will involve invoking fetch-crl, with appropriate arguments.
setCAURL [--url <osg|osg-new|igtf-old|igtf-new|itb|itb-new|itb-igtf-old|itb-igtf-new|vdt|URL>]: This command sets the location from where the CA files. This command will modify vdt-update-certs.conf and set the cacerts_url. Only if --auto-refresh is specified both CA and CRLs are refreshed once the URL change has been made. The distribution <URL> will be required to conform to the VDT CA distribution format (e.g. similar to http://vdt.cs.wisc.edu/software/certificates/vdt-igtf-ca-certs-version). If the <URL> cannot be reached or if it is invalid syntactically (i.e. does not conform to the format requirements) a warning will be issued and no changes will be made. The --force option can be used to force a change ignoring the warning (Of course --force will give a warning that update-vdt-certs will no longer work and make the change anyway.) If URL is left unspecified the <URL> will be set to OSG default. We also define keywords for old and new format CAs from OSG, ITB and VDT caches as shortcuts to indicate well-known CA URLs.
add [--dir <local_dir>] --hash <CA hash>: The --hash argument is required. If --dir is not specified we will assume that the user wants to include a standard CA he has previously excluded (otherwise --dir is required). If <CA hash> is not known or it is already included tool will provide appropriate error/warning information. In the common case this command will add include lines for <local_dir>/<CA hash>.*, (except .r0) into the vdt-update-certs.conf file. Lastly the command will invoke functions refresh the CAs and fetch CRLs (if --auto-refresh is specified). This command will also do some preliminary error checks, e.g. make sure that â€œ.0â€, â€œ.crl_urlâ€ files exist and that --dir is different than --cert-dir.
remove --hash <CA hash>: This command will be complementary to add and would either add an exclude or remove an include depending on the scenario. This command will also refresh CA and CRLs (when specified). vdt-update-certs do the job of actually removing cert files, we will still do the preliminary error checks to make sure that the certs that are being removed are included in the first place.