Provided by: gridengine-common_8.1.9+dfsg-11build3_all bug

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.  There follows a list of possible commands and command
       options to give an overview of what functionality is available. For further details  about
       every command refer to the COMMAND DETAILS section.

COMMAND OVERVIEW

       -help  Show usage.

       -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  the
              Grid Engine daemon, root and admin user.

       -req | -verify cert | -sign | -copy [command options]
              Manipulate individual keys and certificates.

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

       -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", "-catop"
              or "-calocaltop" are set, the corresponding directories are printed.

       -usercert user file | -user u:g:e | -sdm_daemon u:g:e [command options]
              Create certificates and keys for a bunch of users contained in user file, a  single
              user, or SDM daemon in the form u:g:e.

       -pkcs12 user | -sdm_pkcs12 g | -sys_pkcs12 [command options]
              Export  the  certificate and key for user user or SDM daemon g in PKCS12 format and
              to export the Grid Engine daemon certificate and key in PKCS12 format.

       -userks | -ks user | -sysks [command options]
              Create keystore for all users with a certificate and key, the keystore for a single
              user user, or the keystore containing the Grid Engine daemon certificate and key.

       -renew user | -renew_ca | -renew_sys | -renew_sdm g [command options]
              Renew the certificate for user user, for the CA, for the Grid Engine daemon, or the
              SDM daemon with common name g.  The old certificate remains valid until it expires.
              NB. The option of this name was re-named to -rrenew in Grid Engine 8.1.9.

       -rrenew user | -rrenew_ca | -rrenew_sys | -rrenew_sdm g [command options]
              Renew the certificate for user user, for the CA, for the Grid Engine daemon, or the
              SDM daemon with common name g, and revoke the old  ones  (updating  the  revocation
              list).   NB.  This requires unique_subject=no in sge_ssl_template.cnf, which is the
              default for new installations, but might not be set for old ones.

       -revoke cert
              Revoke the certificate cert, which should be  an  actual  PEM  file,  updating  the
              revocation list.

       In the above, "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 as dir.

       -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, and -catop are not used, 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:
              $SGE_ROOT/$SGE_CELL/common/sgeCA (can be overruled by -catop dir or -cadir dir)
              /var/lib/sgeCA/port$SGE_QMASTER_PORT/$SGE_CELL                                   or
              /var/lib/sgeCA/sge_qmaster/$SGE_CELL (can be overruled by -calocaltop dir or -cadir
              dir).
              The following information must be delivered for the site: two letter country  code,
              state,  location,  e.g. city or your building code, organization (e.g. your company
              name), organizational unit, e.g. your department,  and  email  address  of  the  CA
              administrator (you!).

       Certificates  and  keys  are  generated  for  the  CA  itself,  the  Grid  Engine  daemon,
       installation user (usually root), and finally for the 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 other 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  user  certificate  and  keys  for u:g:e, where u is the user id, g is the
              "common name" (real name of the user), and e  is  the  user's  email  address.   By
              default  the certificate is valid for 365 days or for days, as specified with -days
              days.  This command is usually run as user root on the  qmaster  host.  $CATOP  and
              $CALOCALTOP may be overruled by -cadir, -catop, and -calocaltop.

       sge_ca -sdm_daemon u:g:e
              Generate  daemon certificate and keys for u:g:e with parameters and lifetime as for
              -user.  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 for 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 may be overruled by -cadir, -catop, and -calocaltop.

       sge_ca -renew_ca [-cadir dir] [-catop dir] [-calocaltop  dir]  [-adminuser  admin]  [-days
       days]
              Renew the CA certificate, similarly to -renew.

       sge_ca  -renew_sys  [-cadir  dir] [-catop dir] [-calocaltop dir] [-adminuser admin] [-days
       days]
              Renew the Grid Engine daemon certificate, similarly to -renew.

       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,
              similarly to -renew.

       sge_ca  -pkcs12  user  [-pkcs12pwf  file]  [-pkcs12dir  dir]  [-cadir  dir]  [-catop  dir]
       [-calocaltop dir] [-adminuser admin]
              Export  certificate  and  key  of user user (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 may be 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 Grid Engine daemon in PKCS12 format, similarly to
              -pkcs12.

       sge_ca -sdm_pkcs12  g  [-pkcs12pwf  file]  [-pkcs12dir  dir]  [-cadir  dir]  [-catop  dir]
       [-calocaltop dir] [-adminuser admin]
              Export  certificate  and  key  of  SDM daemon with common name g in PKCS12 format,,
              similarly to -renew.

       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 may be 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 0ercert userfile or
              if any of the certificates  have  been  renewed.  $CATOP  and  $CALOCALTOP  may  be
              overruled by -cadir, -catop and -calocaltop.

       sge_ca -sysks [-kspwf file] [-cadir dir] [-catop dir] [-calocaltop dir] [-adminuser admin]
              Generate  a  keystore  containing the Grid Engine 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 may be overruled by -cadir, -catop and -calocaltop.

       sge_ca -print cert
              Print a PEM-format certificate cert.

       sge_ca -printkey key
              Print a PEM-format key key.

       sge_ca -printcrl crl
              Print a PEM-format certificate revocation list crl.

       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.  These  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 certificate's validity where cert is the certificate in pem format. $CATOP
              and $CALOCALTOP can be overruled by -cadir, -catop and -calocaltop.

       sge_ca -copy [-cadir dir] [-catop dir] [-calocaltop dir]
              Run  by  a  user  to  copy  their  certificate  and  key  on  the  master  host  to
              $HOME/.sge/port$SGE_QMASTER_PORT/$SGE_CELL/certs/cert.pem  and  the   corresponding
              private  key  to  $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.

ENVIRONMENT VARIABLES

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

       SGE_CELL       If set, specifies the default Grid Engine cell.

RESTRICTIONS

       The  command  must usually be 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/lib/sgeCA/{port$SGE_QMASTER_PORT|sge_qmaster}/$SGE_CELL  where the subpaths beginning
       with $ expand 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.)

       SGE_ROOT/util/sgeCA/sge_ssl_template.cnf: OpenSSL configuration file.

       SGE_ROOT/util/sgeCA/sge_ssl.cnf: OpenSSL configuration file used for signing.

SEE ALSO

       sge_qmaster(8).

COPYRIGHT

       See sge_intro(1) for a full statement of rights and permissions.