
[[sec_admin]]

The admin client
----------------

The admin client is used to edit the XUUDB, using a web service interface.
It is configured in the file +CONF/xuudb_client.conf+. Client is invoked using the following pattern:

  ADMIN <command> <options>

You can get detailed usage info by calling the admin script without
any options. As it was noted above the actual utility path is dependent on how
XUUDB was installed: it is either +/usr/sbin/unicore-xuudb-admin+ or 
+INST/bin/admin.sh+.

NOTE: to switch on the confirmation message asked by the +add+
command, edit the admin.sh script, so that the +xuudb.batch+ property
is set to +false+.

The client configuration requires the URL of the XUUDB server in the property +xuudb.address+
and in case of secure HTTPS connections also a configuration truststore and credential. The settings
are exactly the same as in case of the XUUDB server, so refer to its documentation: <<authtrust>>.

:leveloffset: 1
include::sec-client.txt[]
:leveloffset: 0



Commands
~~~~~~~~

The help with examples is provided for each command. You can use +helpAll+ to print
a reference documentation for all commands. Selected commands are also described below.

--------------

[classic]
  add
  adddn
  check-cert (chc)
  check-dn (chdn)
  export
  import
  list
  remove
  update

[dynamic]
  findMapping (fm)
  findReverseMapping (fr)
  freezeMappings
  getDynamicAttributes (getDyn)
  listMappings (lm)
  listPools (lp)
  removeMappings
  removePool (rmp)
  simulate (sim)

[other]
  help
  helpAll
-----------------


NOTE: when the server runs in dn mode you can use 'dn=' parameter for remove,
list and update

Common options:

gcID:: 
          The so-called "grid component ID" is used to group entries, and
          must match the setting in the UNICORE/X configuration file
          +uas.config+.  For example if you have two systems with
          different user name mappings, you can handle both with a
          single XUUDB, since you can store two user name mappings for
          each certificate, by choosing a different gcID for both
          systems.
          When updating xuudb entries, the special gcid '*' can be used as
          wildcard for updating user entries on all systems.

pemfile:: 
         A file containing the public key in PEM format 

DN:: 
        The distinguished name of a user

xlogin:: 
  xlogins (from UNIX login) are used for incarnation. Grid user's request which 
results in invocation of operations on a target system (usually through BSS) 
must be mapped to a local UNIX user. This attribute specifies the XLogins which 
are valid for the user. The first one is also used as a default one, if user 
does not request a particular one. Multiple logins can be specified using a +:+

project:: 
      Defines a primary group UNIX group for a user. If it is undefined then a
      default group for the XLogin is used.

role:: 
      The usual roles in UNICORE are +user+ for a normal user, and
      +admin+ for an administrator. Custom roles can be added, and can
      be assigned permissions in the UNICORE/X security policy file.



Adding entries using +add+ or (in DN mode) +adddn+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Example using a pem file:

  $> ADMIN add DEMO-SITE /path/to/usercert.pem userlogin user

Example using the DN (works only if server runs in DN mode):

  $> ADMIN adddn DEMO-SITE "CN=John Doe, O=Test Inc" userlogin user

[NOTE]
=====================================================================
When extracting the DN from a certificate file using OpenSSL,
make sure to use the +RFC2253+ option, for example:

  openssl x509 -in demouser.pem -noout -subject -nameopt RFC2253
=====================================================================


Checking the content
~~~~~~~~~~~~~~~~~~~~

Apart from +list+, you can use the +check-cert+ and +check-dn+
commands to see what the XUUDB contains for a certain certificate or
DN.


Removing entries
~~~~~~~~~~~~~~~~


HINT: before removing you can check with the list command which takes
the same parameters, that your are removing the correct entries. 

To remove all entries from xuudb (you will have to confirm this)

  $> ADMIN remove ALL 

To remove some entries, you have to specify attributes.

To remove a user with cert cert.pem at gcid MYSITE:

   $> ADMIN remove gcid=id001 pemfile=/path/cert.pem

To remove all users from gcid OLDMACHINE:

   $> ADMIN remove gcid=OLDMACHINE

To remove a user with xlogin jdoe from all gcids:

   $> ADMIN remove xlogin=jdoe

etc...


Exporting/importing 
~~~~~~~~~~~~~~~~~~~

The export command creates a csv file, which will contain the complete
XUUDB database:

  $> ADMIN export uudb.csv

If the file already exists, the export tool will complain. To override
this, please specify the +overwrite+ option, e.g.

  $> ADMIN export uudb.csv overwrite

The import command takes the a csv file (as generated by +export+) and
imports all entries. Already existing entries will not be changed.  To
do updates, execute +admin.sh remove ALL+ before, or specify +clearDB+ as a second
argument

  $> ADMIN import uudb.csv


Updating entries
~~~~~~~~~~~~~~~~

The +update+ command can be used to modify existing entries, for example to
replace the certificate or the login. For example,

  $> ADMIN update DEMO-SITE certs/demouser.pem xlogin=jb007

would update the entry identified by the gcID 'DEMO-SITE' and the given pem
file, and assign a new xlogin. If you want to update a user's entry on all 
the sites, you would use

  $> ADMIN update \* certs/demouser.pem xlogin=jb007

Note that the wildcard '*' is a special character for the shell and needs to be
escaped with a backslash.

