release notes | Book: 1.9.5, 1.9.12 (opt, FHS), 2.11 (FHS), 2.12 (FHS), 2.13 (FHS), 2.14 (FHS), | Wiki | Q&A black_bg
Web: Multi-page, Single page | PDF: A4-size, Letter-size | eBook: epub black_bg

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

Note

If you attempt to log into the admin interface without generating the ssh-keys you will get an error message.

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

See the section called “Generating ssh-keys”.

dCache has a powerful administration interface. It is accessed with the ssh protocol. The server is part of the adminDoor domain. Connect to it 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

This already illustrates how to navigate within the administration interface:

Starting from the local prompt ((local) admin >) the command cd takes you to the specified cell (here acm, the access control manager). There two commands are executed. The escape sequence .. takes you back to the local prompt and logoff exits the admin shell.

There also is the command help for listing all commands the cell knows and their parameters. However, many of the commands are only used for debugging and development purposes.

Note

If the cells are well-known, they can be accessed without adding the domain-scope. See Chapter 6, 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:

Example:

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

Note

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

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.

(topo) admin > ..
(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, broadcast, 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 “The Cost Module”.

[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