dcache.8

.TH DCACHE 8 "October 2013" "" ""

.SH NAME
dcache \- The dCache distributed storage resource manager

.SH SYNOPSIS

\fBdcache\fR [OPTION]... COMMAND

.SH DESCRIPTION

This is an init and management script for dCache hosts. For a full
description of dCache and its configuration, please visit the dCache
webpage at http://www.dcache.org.

This script only manages services running on the local host, i.e., all
commands only affect the local host. The script is not intended for
central management of a distributed dCache installation.

.SH STARTUP COMMANDS

.TP
.B start [DOMAIN]...
Starts configured dCache services. If one or more services or domains
are specified, only those services or domains are started. See the
description of the \fBstatus\fR and \fBservices\fR commands on how to
obtain a list of configured domains and services.

.TP
.B stop [DOMAIN]...
Stops running services. If one or more services or domains are
specified, only those services or domains are stopped. See the
description of the \fBstatus\fR and \fBservices\fR commands on how to
obtain a list of configured domains and services.

.TP
.B restart [DOMAIN]...
Restarts configured services. If one or more services or domains
are specified, only those services or domains are restarted. See the
description of the \fBstatus\fR and \fBservices\fR commands on how to
obtain a list of configured domains and services.

.TP
.B condrestart [DOMAIN]...
Restarts running services.  If one or more services or domains are
specified, only those services or domains are restarted. See the
description of the \fBstatus\fR and \fBservices\fR commands on how to
obtain a list of configured domains and services.

.SH MONITORING COMMANDS

.TP
.B status

Reports the status of all configured domains. This includes the
service type provided by the domain, whether the domain is running,
and the current PID of the domain.

Possible domain states are:

.TP.TP
.B stopped
The domain is not running.

.TP.TP
.B running
The domain is running.

.TP.TP
.B orphaned
The wrapper script monitoring the domain has died even though the
domain itself is still running. The wrapper script is responsible for
restarting a domain when it crashes. An orphaned domain is unable to
automatically restart if it crashes.

.TP.TP
.B restarting
The domain quit unexpectedly and is waiting for an automatic restart
by the wrapper script.

.TP
.B services
Provides a list of configured services. This list includes the domain
hosting the service, the service type, the cell name and whether the
service is replicable.

Any service in dCache can have more than one instance if those instances
represent different logical services. Replicable services on the other
hand can have multiple instances representing the same logical service,
i.e. other services see them as a single service. This provides some degree
of fault tolerance and load balancing.

.TP
.B version
Shows the dCache version number.

.SH POOL MANAGEMENTS COMMANDS

.TP
.B pool ls
Provides a list of all configured pools. This list includes the path
to the pool, the pool name, the domain hosting the pool, the meta data
store type, the size of the pool, and the amount of free space on the
file system containing the pool.

.TP
.B pool create [--size=BYTES] [--meta=file|db] [--lfs=MODE] PATH NAME DOMAIN

Creates a new pool in the specified directory. PATH must not
exist. NAME must be a unique pool name. DOMAIN must be a unique dCache
domain name. The directory will be created and populated with the
necessary files to host a pool, and the configuration will be appended
to the layout file.

The \fBsize\fR is specified in bytes or with an optional suffix of K,
M, G or T for kibibytes, mebibytes, gibibytes and tebibytes,
respectively. The size is rounded down to the nearest integer of
gibibytes.

The \fBmeta\fR option configures the meta data backend to use for the
new pool. The default is to use the \fBfile\fR based backend. This
backend creates two meta data files in a control directory for each
data file stored on the pool. The control directory is created in the
pool directory. The \fBdb\fR uses Berkeley DB to store the meta
data. The database is stored in the meta directory underneath the pool
directory.

The \fBlfs\fR option determines the large file store mode of the
pool. The default is \fBnone\fR. Possible values are \fBnone\fR,
\fBprecious\fR, \fBvolatile\fR, and \fBtransient\fR. \fBprecious\fR is
a legacy option. New deployments are encouraged to use per file access
latency and retention policy settings to control whether files are to
be stored on tape or disk. The use of \fBprecious\fR as an LFS mode is
deprecated.

.TP
.B pool convert NAME TYPE

Converts the meta data backend of a pool to a different type. This
facilitates changing the meta data backend type for an existing
pool. NAME is the unique pool name, and TYPE is either \fBfile\fR,
\fBdb\fR, or a meta data store class name.

The pool must not be running at the time it is converted and the
target meta data store must be empty. The source meta data store is
left unmodified.

The pool configuration is not automatically updated. To switch to the
new backend the metaDataRepository property has to be changed
manually. \fBNote\fR that if the pool is started before the property
is changed then meta data store needs to be converted again to avoid
data loss.

.TP
.B pool yaml NAME

Dumps the meta data of a pool to stdout using the human and machine
readable YAML format.

.TP
.B pool reconstruct PATH DESTINATION

Reconstructs the Berkeley DB database containing pool meta data. PATH
is the base path of a pool. DESTINATION is the directory in which the
reconstructed database will be stored. DESTINATION must not exist
prior to calling this command.

The operation is only relevant for pools using the Berkeley DB meta
data backend. Pools using the classic control directory cannot be
reconstructed.

Although the Berkeley DB backend deploys a log structured database, it
can break in case the files get corrupted. This could happen due to OS
failures or hardware failures. In such cases reconstructing the
database is often able to recover most if not all data.

Note that the command creates the database in a new directory. One has
to manually replace the content of the meta directory of the pool with
the reconstructed database. It is recommended to keep a copy of the
old database.

.SH DATABASE MANAGEMENT COMMANDS

Several services in dCache rely on relational databases. The commands
below provide basic schema management functionality for those
databases. By default most services manage their schema
automatically. Use the \fBdatabase ls\fR command below to determine
which databases do.

Most commands below accept a glob pattern for \fBCELL@DOMAIN\fR.

Not all services support these commands yet.

.TP
.B database ls
Lists databases of configured services. Not all services support
listing of their database and those that do not all provide the
management commands below.  If they do, the database is listed with
the MANAGEABLE column showing "Yes".

.TP
.B database update [CELL@DOMAIN]...
Updates the schema to the latest revision.

.TP
.B database showUpdateSQL [CELL@DOMAIN]...
Print the SQL statements which will be applied by update command.

.TP
.B database tag TAG [CELL@DOMAIN]...
Tags the current database schema. See \fBrollback\fR command for
details.

.TP
.B database rollback TAG [CELL@DOMAIN]...
Rolls back the database schema to a tagged revision. Note that only
the schema is rolled back. Any changes to the content of the databases
cannot be rolled back. There is no guarante that all data can be
preserved when rolling back - this depends on the exact changes that
were made. Please consult the release notes for details.

.TP
.B database rollbacktoDate DATE/TIME [CELL@DOMAIN]...
Rolls back the database schema to the state it was in at the given
date/time. Note that only the schema is rolled back. Any changes to
the content of the databases cannot be rolled back. There is no
guarante that all data can be preserved when rolling back - this
depends on the exact changes that were made. Please consult the
release notes for details.

.TP
.B database listLocks [CELL@DOMAIN]...
The database schema will be locked when updated. This command lists
the current schema change locks.

.TP
.B database releaseLocks [CELL@DOMAIN]...
The database schema will be locked when updated. This command releases
all schema change locks. Use this command to remove stale locks left
over from failed schema updates.

.TP
.B database doc CELL@DOMAIN DIR
Generates schema documentation for the database of a service. The
documentation is written as HTML to the output directory specified.

.SH ALARM COMMANDS

.TP
.B alarm send [-d=DOMAIN] [-s=SERVICE] [-t=TYPE] MESSAGE
Command for sending an arbitrary alarm message to the alarm server.  The
remote server address is taken from the local values for dcache.log.server.host
and dcache.log.server.port.

.TP.TP
.B DOMAIN
The domain issuing the alarm; if not given, it defaults to "<na>".

.TP.TP
.B SERVICE
The service or cell issuing the alarm; if not given, it defaults to
"user-command".

.TP.TP
.B TYPE
Additional subtype marker; all alarms are marked ALARM; with type defined,
a submarker is added. The type must belong to the set of
predefined (internal) alarms (use the 'alarm list' command to inspect them);
if left undefined, an attempt will be made to match to any custom definitions
by the server; failing that, the alarm will be marked as of type 'GENERIC'.

.TP
.B alarm list
Displays list of all "marked" alarm types currently defined in dCache code.

.SH MISCELLANEOUS COMMANDS

.TP
.B billing [--format=raw|files|json|yaml] [--since=DATE] [--until=DATE] [-f=FILE] [PATH|PNFSID|DN]...
Searches local billing files for entries for the particular path, PNFS
ID or DN. Complete prefixes of paths and DNs can be searched too. With
\fB-files\fR a list of billing files that are likely to contain the search
term is printed instead. With \fB-f\fR the search terms are read from \fBFILE\fR.
The output format is selected with \fB-format\fR.

.TP
.B kpwd COMMAND [-debug] [ARGUMENT]...
Management commands for the kpwd authentication file. Allows users and
mappings to be created, read, updated, and deleted.

.TP
.B property PROPERTY [DOMAIN [SERVICE]]
Evaluates the value of a PROPERTY in the context of a DOMAIN and SERVICE.

.SH DEBUGGING COMMANDS

.TP
.B check-config
Checks the dCache main configuration file, dcache.conf, and the node's
layout file for any problems with these files' structure or their use
of properties and generates appropriate warning or error messages.
Warning messages describe problems that do not prevent dCache from
starting whereas error messages indicate a problem that must be fixed
before dCache will start correctly.

A warning message is generated if dCache configuration attempts to
assign a value to a deprecated or obsolete property and an error
message is reported if a file attempts to adjust the value of a
forbidden property.

.TP
.B ports
Lists the TCP and UDP ports that dCache is configured to listen on.
For each port, the corresponding domain, service and cell-name is also
listed.

In some cases dCache may listen on a particular port depending on some
external, run-time conditions.  In this case the number is placed in
parentheses.

In other cases, dCache will select ports to listen on from a range of
TCP port numbers.  This is indicated by two numbers separated
by a single dash ('-').

.TP
.B dump heap [--force] DOMAIN FILE
Dumps the Java heap of DOMAIN to FILE. The file will contain
information about all objects and can be analysed with the Java
\fBjhat(1)\fR utility. Note that the file might contain confidential
information, such as host keys.

If the domain hangs, then the dump may fail. In those cases the
\fBforce\fR option can force the dump, however the dump will not be
quite as useful, as it will also contain objects that are no longer in
use.

This feature requires that the Java Development Kit (JDK) package is
installed.

.TP
.B dump threads [SERVICE|DOMAIN] ...
Dumps the Java stack traces of all running threads in DOMAIN or
SERVICE. If no services or domains are specified, stack traces of all
running domains will be dumped. The information is written to the log
files of the respective domains.

.TP
.B dump zklog [PATH]
List the transactions recorded in the ZooKeeper server log files.
These are 'log.' files located within PATH.  If PATH is omitted then
the expanded value of '${zookeeper.data-log-dir}/version-2' is used.
The transaction information is written to standard out.

.SH DEFINITIONS
The following definitions are used throughout this document:

.TP
.B cell
A component of dCache. dCache consists of many cells. A cell must have
a name which is unique within the domain hosting the cell.
.TP
.B domain
A container hosting one or more dCache cells. A domain runs within its
own process. A domain must have a name which is unique throughout the
dCache instance.
.TP
.B well known cell
A cell which name is published to other domains. Well known cells can
be addressed without knowing the domain hosting the cell. Well known
cells must have a name which is unique throughout the dCache instance.
.TP
.B service
An abstraction used in the dCache configuration to describe atomic
units to add to a domain. A service is typically implemented through
one or more cells.
.TP
.B layout
A set of named domains and a description of the services of each. The
layout may contain domain and service specific configuration values.
.TP
.B pool
A cell providing physical data storage services.

.SH WHAT IS DCACHE

The core part of the dCache has proven to combine heterogenous disk
storage systems in the order of several peta bytes and let its data
repository appear under a single filesystem tree. It takes care of
data hot spots, failing hardware and makes sure, if configured, that
at least a minimum number of copies of each dataset resides within the
system to ensure full data availability in case of disk server
maintainance or failure. Furthermore, dCache supports a large set of
standard access protocols to the data repository and its namespace.

If dCache is connected to a Tertiary Storage System, it optimizes
access to such a system by various techniques. Currently Enstore, the
Open Storage Manager (OSM), the High Performance Storage System (HPSS)
and the Tivoli Storage Manager (TSM) are supported by the dCache
middleware.

Moreover, dCache/SRM supports all interfaces of the LCG storage
element definition.

.SH PROJECT PARTNERS

dCache is a joint venture between the Deutsches Elektronen-Synchrotron
(DESY), the Fermi National Accelerator Laboratory (FNAL), and the
Nordic Data Grid Facility (NDGF).