SGE_CA(8)

NAME
util/sgeCA/sge_ca - Grid Engine CSP Support control command

SYNTAX
sge_ca command [command options]

DESCRIPTION
sge_ca controls a simple Grid Engine Certificate Authority that is used for the special Certificate Security Protocol (CSP) mode. CSP mode improves the security behavior of Grid Engine by enabling OpenSSL secured communication channels and X509v3 certificates for authentication. In addition it is possible to export the key material or to create JKS keystores for the JMX connector. It follows a list of possible commands and command options to give an overview which functionality is available. For further details about every command refer to the COMMAND DETAILS section.

COMMAND OVERVIEW

sge_ca [-help]
    show usage

sge_ca -init [command options]
    create the infrastructure for a new Grid Engine Certificate Authority with its corresponding files and directories and a set of keys and certificates for SGE Daemon, root and admin user.

sge_ca -req | -verify <cert> | -sign | -copy [command options]
    manipulate individual keys and certificates

sge_ca -print <cert> | -printkey <key> | -printcrl <crl>
    print out certificates, keys and certificate revocation lists in human readable form.

sge_ca -showCaTop | -showCaLocalTop [command options]
    echo the $CATOP or $CALOCALTOP directory. This command is usually run as root on the qmaster host after a CA infrastructure has been created. If "-cadir" or "-catop" or "-calocaltop" are set the corresponding directories are printed.

sge_ca -usercert <user file> | -user <u:g:e> | -sdm_daemon <u:g:e> [command options]
    are used for creation of certificates and keys for a bunch of users contained in <user file>, a single user or SDM daemon <u:g:e>. (see )

sge_ca -pkcs12 <user> | -sdm_pkcs12 <g> | -sys_pkcs12 [command options]
    are used to export the certificate and key for user <user> or SDM daemon <g> in pkcs12 format and to export the SGE Daemon certificate and key in pkcs12 format.

sge_ca -userks | -ks <user> | -sysks [command options]
    are used for creation of keystore for all users with a certificate and key, the keystore for a single user <user> and the keystore containing the SGE Daemon certificate and key.

sge_ca -renew <user> | -renew_ca | -renew_sys | -renew_sdm <g> [command options]
    are used to renew the corresponding certificates for user <user>, for the CA, for the SGE Daemon certificate and for the SDM daemon <g> certificate.

where "[command options]" is a combination of the following options depending on the command. The COMMAND DETAILS section explains which options are usable for each command.

-days <days>
    days of validity of the certificate

-sha1
    use sha-1 instead of md5 as message digest

-encryptkey
    use des to encrypt the generated private key with a passphrase. The passphrase is requested when a key is created or used.

-outdir <dir>
    write to directory <dir>

-cahost <host>
    define CA hostname (CA master host)

-cadir <dir>
    define $CALOCALTOP and $CATOP settings

-calocaltop <dir>
    define $CALOCALTOP setting

-catop <dir>
    define $CATOP setting

-kspwf <file>
    define a keystore password file that contains a password that is used to encrypt the keystore and the keys contained therein

-ksout <file>
    define output file to write the keystore to

-pkcs12pwf <file>
    define a pkcs12 password file that contains a password that is used to encrypt the pkcs12 export file and the keys contained therein

-pkcs12dir <dir>
    define the output directory <dir> to write the exported pkcs12 format file to. Otherwise the current working directory is used.

COMMAND DETAILS

sge_ca -init [-cadir <dir>] [-catop <dir>] [-calocaltop <dir>] [-adminuser <admin>] [-days <num days>]
    The -init command creates a new Grid Engine certificate authority and its corresponding files. Usually "sge_ca -init" is run by user root on the master host. If the options -adminuser, -cadir, -calocaltop, -catop and the Grid Engine environment variables SGE_ROOT, SGE_CELL and SGE_QMASTER_PORT are set the CA directories are created in the following locations:
    two letter country code, state, location, e.g city or your buildingcode, organization (e.g. your company name), organizational unit, e.g. your department, email address of the CA administrator (you!) Certificates and keys are generated for the CA itself, for SGE Daemon, for GE install user (usually root) and finally for the GE admin user. How and where the certificates and keys are created can be influenced additionally by:
    -days <days> change the time of validity of the certificates to number of <days> instead of 365 days
    -sha1 change the message digest algorithm from md5 to sha-1
    -encryptkey encrypt the generated keys with a passphrase
    -adminuser <user> use <user> as admin user
    -cahost <host> use <host> as the CA master host
    [-cadir <dir>] [-catop <dir> [-calocaltop <dir>] set $CATOP and $CALOCALTOP to <dir> to use something different than the Grid Engine default directories. Either -cadir <dir> has to be specified to replace $CATOP and $CALOCALTOP by the same directory or -catop <dir> for $CATOP and -calocaltop <dir> for $CALOCALTOP.

sge_ca -user <u:g:e> [-cadir <dir>] [-catop <dir>] [-calocaltop <dir>] [-adminuser <admin>] [-days <days>]
    generate certificate and keys for <u:g:e> with u='Unix user account name', g='common name' and e='email address'. By default the certificate is valid for 365 days or by <days> specified with -days <days>. This command is usually run as user root on the qmaster host. $CATOP and $CALOCALTOP maybe overruled by -cadir, -catop and -calocaltop.

sge_ca -sdm_daemon <u:g:e>
    generate daemon certificate and keys for <u:g:e> with u='Unix user account name', g='common name' and e='email address'. By default the certificate is valid for 365 days or by <days> specified with "-days <days>". This command is usually run as user root on the qmaster host.

sge_ca -usercert <user file> [-cadir <dir>] [-catop <dir>] [-calocaltop <dir>] [-adminuser <admin>] [-days <days>] [-encryptkey] [-sha1]
    Usually sge_ca -usercert <user file> is run as user root on the master host. The argument <user file> contains a list of users in the following format:
             eddy:Eddy Smith:eddy@griders.org
                 sarah:Sarah Miller:sarah@griders.org
                     leo:Leo Lion:leo@griders.org

                where the fields separated by colon are:
                         Unix user:Gecos field:email address

                sge_ca -renew <user> [-cadir <dir>] [-catop <dir>] [-calocaltop <dir>] [-adminuser <admin>] [-days <days>]
                    Renew the certificate for <user>. By default the certificate is extended for 365 days or by <days> specified with -days <days>. If the value is negative the certificate becomes invalid. This command is usually run as user root on the qmaster host. $CATOP and $CALOCALTOP maybe overruled by -cadir, -catop and -calocaltop.

                sge_ca -renew_ca [-cadir <dir>] [-catop <dir>] [-calocaltop <dir>] [-adminuser <admin>] [-days <days>]
                    Renew the CA certificate. By default the certificate is extended for 365 days or by <days> specified with -days <days>. If the value is negative the certificate becomes invalid. This command is usually run as user root on the qmaster host. $CATOP and $CALOCALTOP maybe overruled by -cadir, -catop and -calocaltop.

                sge_ca -renew_sys [-cadir <dir>] [-catop <dir>] [-calocaltop <dir>] [-adminuser <admin>] [-days <days>]
                    Renew the SGE Daemon certificate. By default the certificate is extended for 365 days or by <days> specified with -days <days>. If the value is negative the certificate becomes invalid. This command is usually run as user root on the qmaster host. $CATOP and $CALOCALTOP maybe overruled by -cadir, -catop and -calocaltop.

                sge_ca -renew_sdm <g> [-cadir <dir>] [-catop <dir>] [-calocaltop <dir>] [-adminuser <admin>] [-days <days>]
                    Renew the SDM daemon certificate of <g>, where <g> is the common name of the daemon. By default the certificate is extended for 365 days or by <days> specified with -days <days>. If the value is negative the certificate becomes invalid. This command is usually run as user root on the qmaster host. $CATOP and $CALOCALTOP maybe overruled by -cadir, -catop and -calocaltop.

                sge_ca -pkcs12 <user> [-pkcs12pwf <file>] [-pkcs12dir <dir>] [-cadir <dir>] [-catop <dir>] [-calocaltop <dir>] [-adminuser <admin>]
                    export certificate and key of user <user> 'the Unix user name' in pkcs12 format. This command is usually run as user root on the qmaster host. If -pkcs12pwf <file> is used the file and the corresponding key will be encrypted with the password in <file>. If -pkcs12dir <dir> is used the output file is written into <dir>/<user>.p12 instead of ./<user>.p12 . $CATOP and $CALOCALTOP maybe overruled by -cadir, -catop and -calocaltop.

                sge_ca -sys_pkcs12 [-pkcs12pwf <file>] [-pkcs12dir <dir>] [-cadir <dir>] [-catop <dir>] [-calocaltop <dir>] [-adminuser <admin>]
                    export certificate and key of SGE Daemon in pkcs12 format. This command is usually run as user root on the qmaster host. If -pkcs12pwf <file> is used the file and the corresponding key will be encrypted with the password in <file>. If -pkcs12dir <dir> is used the output file is written into <dir>/<user>.p12 instead of ./<user>.p12 . $CATOP and $CALOCALTOP maybe overruled by -cadir, -catop and -calocaltop.

                sge_ca -sdm_pkcs12 <g> [-pkcs12pwf <file>] [-pkcs12dir <dir>] [-cadir <dir>] [-catop <dir>] [-calocaltop <dir>] [-adminuser <admin>]
                    export certificate and key of daemon <g> g='common name' in pkcs12 format. This command is usually run as user root on the qmaster host. If -pkcs12pwf <file> is used the file and the corresponding key will be encrypted with the password in <file>. If -pkcs12dir <dir> is used the output file is written into <dir>/<g>.p12 instead of ./<g>.p12 . $CATOP and $CALOCALTOP maybe overruled by -cadir, -catop and -calocaltop.

                sge_ca -ks <user> [-ksout <file>] [-kspwf <file>] [-cadir <dir>] [-catop <dir>] [-calocaltop <dir>] [-adminuser <admin>]
                    create a keystore containing certificate and key of user <user> in JKS format where <user> is the Unix user name. This command is usually run as user root on the qmaster host. If -kspwf <file> is used the keystore and the corresponding key will be encrypted with the password in <file>. The -ksout <file> option specifies the keystore file that is created. If the -ksout <file> option is missing the default location for the keystore is $CALOCALTOP/userkeys/<user>/keystore. This command is usually invoked by sge_ca -userks. A prerequisite is a valid JAVA_HOME environment variable setting. $CATOP and $CALOCALTOP maybe overruled by -cadir, -catop and -calocaltop.

                sge_ca -userks [-kspwf <file>] [-cadir <dir>] [-catop <dir>] [-calocaltop <dir>] [-adminuser <admin>]
                    generate a keystore in JKS format for all users having a key and certificate. This command is usually run as user root on the qmaster host. If -kspwf <file> is used the keystore and the corresponding key will be encrypted with the password in <file>. The keystore files are created in $CALOCALTOP/userkeys/<user>/keystore. This command is run after user certificates and keys have been created with sge_ca -usercert <userfile> or if any of the certificates have been renewed. $CATOP and $CALOCALTOP maybe overruled by -cadir, -catop and -calocaltop.

                sge_ca -sysks [-kspwf <file>] [-cadir <dir>] [-catop <dir>] [-calocaltop <dir>] [-adminuser <admin>]
                    generate a keystore containing the SGE Daemon certificate and key in JKS format. This command is usually run as user root on the qmaster host. If -kspwf <file> is used the keystore and the corresponding key will be encrypted with the password in <file>. The keystore file is created in $CALOCALTOP/private/keystore. $CATOP and $CALOCALTOP maybe overruled by -cadir, -catop and -calocaltop.

                sge_ca -print <cert>
                    Print a certificate where <cert> is the corresponding certificate in pem format.

                sge_ca -printkey <key>
                    Print a key where <key> is the corresponding key in pem format.

                sge_ca -printcrl <crl>
                    Print a certificate revocation list where <crl> is the corresponding certificate revocation list in pem format.

                sge_ca -printcrl <crl>
                    Print a certificate revocation list where <crl> is the corresponding certificate revocation list in pem format.

                sge_ca -req [-cadir <dir>] [-catop <dir>] [-calocaltop <dir>] [-adminuser <admin>] [-days <days>] [-encryptkey] [-sha1] [-outdir <dir>]
                    create a private key and a certificate request for the calling user. This are created as newkey.pem and newreq.pem in the current working directory. If the option -outdir <dir> is specified in addition the files are created in <dir>.

                sge_ca -sign [-cadir <dir>] [-catop <dir>] [-calocaltop <dir>] [-adminuser <admin>] [-days <days>] [-encryptkey] [-sha1] [-outdir <dir>
                    Sign a certificate request. The CA certificate under $CATOP (default: $SGE_ROOT/$SGE_CELL/common/sgeCA) and CA key from $CALOCALTOP (default: /var/sgaCA/{port$SGE_QMASTER_PORT|sge_qmaster}/$SGE_CELL) are used for the signature. If $CATOP and $CALOCALTOP are set to a different directory the information there is used. The certificate is created as newcert.pem in the current working directory or in <dir> if the option -outdir <dir> has been specified. In addition the option "-days <number of days>" can be specified to change the default validity from 365 to number of days.

                sge_ca -verify <cert> [-cadir <dir>] [-catop <dir>] [-calocaltop <dir>] [-adminuser <admin>]
                    Verify a certificates validity where <cert> is the corresponding certificate in pem format. $CATOP and $CALOCALTOP can be overruled by -cadir, -catop and -calocaltop.

                sge_ca -copy [-cadir <dir>] [-catop <dir>] [-calocaltop <dir>]
                    sge_ca -copy is run by a user to copy the users certificate and key on the master host to $HOME/.sge/port$SGE_QMASTER_PORT/$SGE_CELL/certs/cert.pem and the corresponding private key in $HOME/.sge/port$SGE_QMASTER_PORT/$SGE_CELL/private/key.pem which are used instead of the files in $CATOP and $CALOCALTOP. The command is only recommended for testing purposes or where $HOME is on a secure shared file system.

EXAMPLES

# sge_ca -init -cadir /tmp -sha1 -encryptkey -days 31
    create a CA infrastructure in /tmp with a certificate validity of 31 days using sha-1 instead of md5 as message digest.The keys are encrypted and a passphrase has to be entered during the creation of the different keys or during signing a certificate with the created CA key.

# sge_ca -usercert /tmp/myusers.txt -cadir /tmp
    /tmp/myusers.txt contains user1:My User:user1@myorg.org and user1 is a valid Unix user account. Create a key and certificate for user1.

# sge_ca -userks -cadir /tmp
    create a keystore for all users of the simple CA. The keystore is stored under /tmp/userkeys/<user>/keystore.

# sge_ca -renew root -cadir /tmp -days -1
    make the root certificate temporarily invalid.

# sge_ca -renew_ca -days 365 -cadir /tmp
    renew the CA certificate for 365 days

ENVIRONMENTAL VARIABLES

SGE_ROOT
    Specifies the location of the Grid Engine standard configuration files.

SGE_CELL
    If set, specifies the default Grid Engine cell.

RESTRICTIONS
sge_ca The command must be usually called with Grid Engine root permissions on the master host. For more details on the permission requirements consult the detailed description for the different commands above.

FILES
sge_ca creates a file tree starting in $CATOP and $CALOCALTOP. The default for $CATOP is usually $SGE_ROOT/$SGE_CELL/common/sgeCA and for $CALOCALTOP /var/sgeCA/{port$SGE_QMASTER_PORT|sge_qmaster}/$SGE_CELL where the subpaths beginning with $ expands to the content of the corresponding environment variable. In addition there may optionally exist the user certificate in $HOME/.sge/port$SGE_QMASTER_PORT/$SGE_CELL/certs/cert.pem and the corresponding private key in $HOME/.sge/port$SGE_QMASTER_PORT/$SGE_CELL/private/key.pem which are used instead of the files in $CATOP and $CALOCALTOP. (see sge_ca -copy above)

SEE ALSO

COPYRIGHT
See for a full statement of rights and permissions.