The Admin Interface

release notes | Book: 2.16, 3.0, 3.1, 3.2, 4.0, 4.1, 4.2 | Wiki | Q&A black_bg

Web: Multi-page, Single page | PDF: A4-size, Letter-size | eBook: epub black_bg

The Admin Interface
Prev	Chapter 3. Getting in Touch with dCache	Next

> > >

The Admin Interface

Just use commands that are documented here

Only commands described in this documentation should be used for the administration of a dCache system.

[return to top]

First steps

dCache has a powerful administration interface. It can be accessed with the ssh1 or with the ssh2 protocol. The server is part of the adminDoor domain.

It is useful to define the admin service in a seperate domain. This allowes to restart the admin service seperatly from other services. In the example in the section called “Installing a dCache instance” this domain was called adminDoorDomain.

Example:

[adminDoorDomain]
[adminDoorDomain/admin]

Note

The admin interface is using ssh2. It used to be available using ssh1, which is insecure and therefore discouraged. If you want to run the admin service with ssh1 you need to define the ssh1 service.

Example:

[adminDoorDomain]
[adminDoorDomain/ssh1]

[return to top]

Access with `ssh2`

There are two ways of authorizing administrators to access the dCache ssh2 admin interface. The preferred method authorizes users through their public key. The second method employs gPlazma2 and the dcache.kpwd file. Thereby authorization mechanisms can be added later by deploying another gPlazma2 plugin. The configuration of both authorization mechanisms is described in the following.

Note

All configurable values of the ssh2 admin interface can be found in the /usr/share/dcache/defaults/admin.properties file. Please do NOT change any value in this file. Instead enter the key value combination in the /etc/dcache/dcache.conf.

[return to top]

Public Key Authorization

To authorize administrators through their public key just insert it into the file authorized_keys2 which should by default be in the directory /etc/dcache/admin as specified in the file /usr/share/dcache/defaults/admin.properties under admin.paths.authorized-keys=. Keys have to be in one line and should have a standard format, such as:

ssh-dss AAAAB3....GWvM= /Users/JohnDoe/.ssh/id_dsa

Important

Please make sure that the copied key is still in one line. Any line-break will prevent the key from being read.

Note

You may omit the part behind the equal sign as it is just a comment and not used by dCache.

Key-based authorization will always be the default. In case the user key can not be found in the file authorized_keys2 or the file does not exist, ssh2Admin will fall back to authorizing the user via gPlazma2 and the dcache.kpwd file.

Now you can login to the admin interface by

[user] $ ssh -l admin -p 22224 headnode.example.org

    dCache Admin (VII) (user=admin)


(local) admin >

[return to top]

Access via `gPlazma2` and the `dcache.kpwd` File

To use gPlazma make sure that you defined a gPlazmaDomain in your layout file.

Example:

Part of the layout file in /etc/dcache/layouts:

[<gplazma-${host.name}>Domain]
[<gplazma-${host.name}>Domain/gplazma]

To use gPlazma2 you need to specify it in the /etc/dcache/dcache.conf file:

# This is the main configuration file of dCache.
#
...
#
# use gPlazma2
gplazma.version=2

Moreover, you need to create the file /etc/dcache/gplazma.conf with the content

auth optional kpwd "kpwd=/etc/dcache/dcache.kpwd"
map optional kpwd "kpwd=/etc/dcache/dcache.kpwd"
session optional kpwd "kpwd=/etc/dcache/dcache.kpwd"

and add the user admin to the /etc/dcache/dcache.kpwd file using the dcache script.

Example:

[user] $ dcache kpwd dcuseradd admin -u 12345 -g 1000 -h / -r / -f / -w read-write -p password
writing to /etc/dcache/dcache.kpwd :

done writing to /etc/dcache/dcache.kpwd :

[user] $

adds this to the /etc/dcache/dcache.kpwd file:

# set pwd
passwd admin 4091aba7 read-write 12345 1000 / /

Edit the file /etc/dcache/dcachesrm-gplazma.policy to switch on the kpwd-plugin. For more information about gPlazma see Chapter 10, Authorization in dCache.

Now the user admin can login to the admin interface with his password password by:

[user] $ ssh -l admin -p 22224 headnode.example.org
admin@headnode.example.org's password:

    dCache Admin (VII) (user=admin)


(local) admin >

To allow other users access to the admin interface add them to the /etc/dcache/dcache.kpwd file as described above.

Just adding a user in the dcache.kpwd file is not sufficient. The generated user also needs access rights that can only be set within the admin interface itself.

See the section called “Create a new user” to learn how to create the user in the admin interface and set the rights.

[return to top]

Access with `ssh1`

Connect to the server using ssh1 with:

[user] $ ssh -c blowfish -p 22223 -l admin headnode.example.org

The initial password is “dickerelch” (which is German for “fat elk”) and you will be greeted by the prompt

   dCache Admin (VII) (user=admin)


(local) admin >

The password can now be changed with

(local) admin > cd acm
(acm) admin > create user admin
(acm) admin > set passwd -user=admin <newPasswd> <newPasswd>
(acm) admin > ..
(local) admin > logoff

[return to top]

How to use the Admin Interface

The command help lists all commands the cell knows and their parameters. However, many of the commands are only used for debugging and development purposes.

Warning

Some commands are dangerous. Executing them without understanding what they do may lead to data loss.

Starting from the local prompt ((local) admin >) the command cd takes you to the specified cell. In general the address of a cell is a concatenation of cell name @ symbol and the domain name. cd to a cell by:

(local) admin > cd <cellName>@<domainName>

Note

If the cells are well-known, they can be accessed without adding the domain-scope. See Chapter 5, The Cell Package for more information.

The domains that are running on the dCache-instance, can be viewed in the layout-configuration (see Chapter 2, Installing dCache). Additionally, there is the topo cell, which keeps track of the instance’s domain topology. If it is running, it can be used to obtain the list of domains the following way:

Note

The topo cell rescans every five minutes which domains are running, so it can take some time until ls displays the full domain list.

Example:

As the topo cell is a well-known cell you can cd to it directly by cd topo.

Use the command ls to see which domains are running.

(local) admin > cd topo
(topo) admin > ls
adminDoorDomain
gsidcapDomain
dcapDomain
utilityDomain
gPlazmaDomain
webdavDomain
gridftpDomain
srmDomain
dCacheDomain
httpdDomain
namespaceDomain
poolDomain
(topo) admin > ..
(local) admin >

The escape sequence .. takes you back to the local prompt.

The command logoff exits the admin shell.

If you want to find out which cells are running on a certain domain, you can issue the command ps in the System cell of the domain.

Example:

For example, if you want to list the cells running on the poolDomain, cd to its System cell and issue the ps command.

(local) admin > cd System@poolDomain
(System@poolDomain) admin > ps
  Cell List
------------------
c-dCacheDomain-101-102
System
pool_2
c-dCacheDomain-101
pool_1
RoutingMgr
lm

The cells in the domain can be accessed using cd together with the cell-name scoped by the domain-name. So first, one has to get back to the local prompt, as the cd command will not work otherwise.

Note

Note that cd only works from the local prompt. If the cell you are trying to access does not exist, the cd command will complain.

Example:

(local) admin > cd nonsense
java.lang.IllegalArgumentException: Cannot cd to this cell as it doesn't exist

Type .. to return to the (local) admin > prompt.

Login to the routing manager of the dCacheDomain to get a list of all well-known cells you can directly cd to without having to add the domain.

Example:

(System@poolDomain) admin > ..
(local) admin > cd RoutingMgr@dCacheDomain
(RoutingMgr@dCacheDoorDomain) admin > ls
Our routing knowledge :
 Local : [PoolManager, topo, LoginBroker, info]
 adminDoorDomain : [pam]
 gsidcapDomain : [DCap-gsi-example.dcache.org]
 dcapDomain : [DCap-example.dcache.org]
 utilityDomain : [gsi-pam, PinManager]
 gPlazmaDomain : [gPlazma]
 webdavDomain : [WebDAV-example.dcache.org]
 gridftpDomain : [GFTP-example.dcache.org]
 srmDomain : [RemoteTransferManager, CopyManager, SrmSpaceManager, SRM-example.dcache.org]
 httpdDomain : [billing, srm-LoginBroker, TransferObserver]
 poolDomain : [pool_2, pool_1]
 namespaceDomain : [PnfsManager, dirLookupPool, cleaner]

All cells know the commands info for general information about the cell and show pinboard for listing the last lines of the pinboard of the cell. The output of these commands contains useful information for solving problems.

It is a good idea to get aquainted with the normal output in the following cells: PoolManager, PnfsManager, and the pool cells (e.g., <poolHostname>_1).

The most useful command of the pool cells is rep ls. To execute this command cd into the pool. It lists the files which are stored in the pool by their pnfs IDs:

Example:

(RoutingMgr@dCacheDoorDomain) admin > ..
(pool_1) admin > rep ls
000100000000000000001120 <-P---------(0)[0]> 485212 si={myStore:STRING}
000100000000000000001230 <C----------(0)[0]> 1222287360 si={myStore:STRING}

Each file in a pool has one of the 4 primary states: “cached” (<C---), “precious” (<-P--), “from client” (<--C-), and “from store” (<---S).

See the section called “How to Store-/Restore files via the Admin Interface” for more information about rep ls.

The most important commands in the PoolManager are: rc ls and cm ls -r.

rc ls lists the requests currently handled by the PoolManager. A typical line of output for a read request with an error condition is (all in one line):

Example:

(pool_1) admin > ..
(local) admin > cd PoolManager
(PoolManager) admin > rc ls
000100000000000000001230@0.0.0.0/0.0.0.0 m=1 r=1 [<unknown>]
[Waiting 08.28 19:14:16]
{149,No pool candidates available or configured for 'staging'}

As the error message at the end of the line indicates, no pool was found containing the file and no pool could be used for staging the file from a tertiary storage system.

See the section called “Obtain information via the dCache Command Line Admin Interface” for more information about the command rc ls

Finally, cm ls with the option -r gives the information about the pools currently stored in the cost module of the pool manager. A typical output is:

Example:

(PoolManager) admin > cm ls -r
pool_1={R={a=0;m=2;q=0};S={a=0;m=2;q=0};M={a=0;m=100;q=0};PS={a=0;m=20;q=0};PC={a=0;m=20;q=0};
    (...continues...)   SP={t=2147483648;f=924711076;p=1222772572;r=0;lru=0;{g=20000000;b=0.5}}}
pool_1={Tag={{hostname=example.org}};size=0;SC=0.16221282938326134;CC=0.0;}
pool_2={R={a=0;m=2;q=0};S={a=0;m=2;q=0};M={a=0;m=100;q=0};PS={a=0;m=20;q=0};PC={a=0;m=20;q=0};
    (...continues...)   SP={t=2147483648;f=2147483648;p=0;r=0;lru=0;{g=4294967296;b=250.0}}}
pool_2={Tag={{hostname=example.org}};size=0;SC=2.7939677238464355E-4;CC=0.0;}

While the first line for each pool gives the information stored in the cache of the cost module, the second line gives the costs (SC: space cost, CC: performance cost) calculated for a (hypothetical) file of zero size. For details on how these are calculated and their meaning, see the section called “Classic Partitions”.

[return to top]

Create a new user

To create a new user, <new-user> and set a new password for the user cd from the local prompt ((local) admin >) to the acm, the access control manager, and run following command sequence:

(local) admin > cd acm
(acm) admin > create user <new-user>
(acm) admin > set passwd -user=<new-user> <newPasswd> <newPasswd>

For the new created users there will be an entry in the directory /etc/dcache/admin/users/meta.

Note

As the initial user admin has not been created with the above command you will not find him in the directory /etc/dcache/admin/users/meta.

Give the new user access to a particular cell:

(acm) admin > create acl cell.<cellName>.execute
(acm) admin > add access -allowed cell.<cellName>.execute <new-user>

Example:

Give the new user access to the PnfsManager.

(acm) admin > create acl cell.PnfsManager.execute
(acm) admin > add access -allowed cell.PnfsManager.execute <new-user>

Now you can check the permissions by:

(acm) admin > check cell.PnfsManager.execute <new-user>
Allowed
(acm) admin > show acl cell.PnfsManager.execute
<noinheritance>
<new-user> -> true

The following commands allow access to every cell for a user <new-user>:

(acm) admin > create acl cell.*.execute
(acm) admin > add access -allowed cell.*.execute <new-user>

The following command makes a user as powerful as admin (dCache’s equivalent to the root user):

(acm) admin > create acl *.*.*
(acm) admin > add access -allowed *.*.* <new-user>

[return to top]

Use of the `ssh` Admin Interface by scripts

The ssh admin interface can be used non-interactively by scripts. For this the dCache-internal ssh server uses public/private key pairs.

The file /etc/dcache/authorized_keys contains one line per user. The file has the same format as ~/.ssh/authorized_keys which is used by sshd. The keys in /etc/dcache/authorized_keys have to be of type RSA1 as dCache only supports SSH protocol 1. Such a key is generated with

[user] $ ssh-keygen -t rsa1 -C 'SSH1 key of <user>'
Generating public/private rsa1 key pair.
Enter file in which to save the key (/home/<user>/.ssh/identity):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/<user>/.ssh/identity.
Your public key has been saved in /home/<user>/.ssh/identity.pub.
The key fingerprint is:
c1:95:03:6a:66:21:3c:f3:ee:1b:8d:cb:46:f4:29:6a SSH1 key of <user>

The passphrase is used to encrypt the private key (now stored in /home/<user>/.ssh/identity). If you do not want to enter the passphrase every time the private key is used, you can use ssh-add to add it to a running ssh-agent. If no agent is running start it with

[user] $ if [ -S $SSH_AUTH_SOCK ] ; then echo "Already running" ; else eval `ssh-agent` ; fi

and add the key to it with

[user] $ ssh-add
Enter passphrase for SSH1 key of <user>:
Identity added: /home/<user>/.ssh/identity (SSH1 key of <user>)

Now, insert the public key ~/.ssh/identity.pub as a separate line into /etc/dcache/authorized_keys. The comment field in this line “SSH1 key of <user>” has to be changed to the dCache user name. An example file is:

1024 35 141939124(... many more numbers ...)15331 admin

Using ssh-add -L >> /etc/dcache/authorized_keys will not work, because the line added is not correct. The key manager within dCache will read this file every minute.

Now, the ssh program should not ask for a password anymore. This is still quite secure, since the unencrypted private key is only held in the memory of the ssh-agent. It can be removed from it with

[user] $ ssh-add -d
Identity removed: /home/<user>/.ssh/identity (RSA1 key of <user>)

In scripts, one can use a “Here Document” to list the commands, or supply them to ssh as standard-input (stdin). The following demonstrates using a Here Document:

#!/bin/sh
#
#  Script to automate dCache administrative activity

outfile=/tmp/$(basename $0).$$.out

ssh -c blowfish -p 22223 admin@<adminNode> > $outfile << EOF
cd PoolManager
cm ls -r
(more commands here)
logoff
EOF

or, the equivalent as stdin.

#!/bin/bash
#
#   Script to automate dCache administrative activity.

echo -e 'cd <pool_1>\nrep ls\n(more commands here)\nlogoff' \
  | ssh -c blowfish -p 22223 admin@<adminNode> \
  | tr -d '\r' > rep_ls.out

Prev	Up	Next
The Web Interface for Monitoring dCache	Home	Authentication and Authorization in dCache

The Admin Interface

Just use commands that are documented here

First steps

Note

Access with ssh2

Note

Public Key Authorization

Important

Note

Access via gPlazma2 and the dcache.kpwd File

Access with ssh1

How to use the Admin Interface

Warning

Note

Note

Note

Create a new user

Note

Use of the ssh Admin Interface by scripts

Access with `ssh2`

Access via `gPlazma2` and the `dcache.kpwd` File

Access with `ssh1`

Use of the `ssh` Admin Interface by scripts