.\" @project The CERN Tape Archive (CTA) .\" @copyright Copyright © 2020-2022 CERN .\" @license This program is free software, distributed under the terms of the GNU General Public .\" Licence version 3 (GPL Version 3), copied verbatim in the file "COPYING". You can .\" redistribute it and/or modify it under the terms of the GPL Version 3, or (at your .\" option) any later version. .\" .\" This program is distributed in the hope that it will be useful, but WITHOUT ANY .\" WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A .\" PARTICULAR PURPOSE. See the GNU General Public License for more details. .\" .\" In applying this licence, CERN does not waive the privileges and immunities .\" granted to it by virtue of its status as an Intergovernmental Organization or .\" submit itself to any jurisdiction. .TH CTA-ADMIN "1cta" "2022-06-30" "CTA" "The CERN Tape Archive (CTA)" .SH NAME cta-admin \- Administrative command interface for CTA tape system operators .SH SYNOPSIS \fBcta-admin\fP [--json] [--config] \fIcommand\fR [\fIsubcommand\fR] [\fIoptions\fR] .SH DESCRIPTION .P \fBcta-admin\fP sends the specified command to the CTA Frontend (see \fBCONFIGURATION\fR below). .P Invoking \fBcta-admin\fP with no command line parameters shows a list of valid commands. To show the subcommands and options for a specific command, type: .P .RS \fBcta-admin\fP \fIcommand\fR help .RE .SS Commands Commands have a long version and an abbreviated version (shown in brackets). .TP activitymountrule (amr) Add, change, remove or list the activity mount rules. This is provided as an alternative to requester mount rules and group mount rules, where the scheduling priority is based on metadata sent by the client rather than the authenticated identity of the requestor. .TP admin (ad) Add, change, remove or list the administrators of the system. In order to use \fBcta-admin\fP, users must exist in the administrator list and must authenticate themselves with a valid Kerberos KRB5 credential. .TP archiveroute (ar) Add, change, remove or list the archive routes, which are the policies linking namespace entries to tape pools. .TP diskinstance (di) Add, change, remove or list the disk instances. A CTA installation has one or more disk instances. A disk instance is a separate namespace. Multiple disk instances should be configured if it is desired to have a separate namespace for each Virtual Organization (VO). .TP diskinstancespace (dis) Add, change, remove or list the disk instance spaces. A disk instance can contain zero or more disk instance spaces. A disk instance space is a partition of the disk. For example, it can be desirable to have separate spaces for archival and retrieval operations on each instance. .TP disksystem (ds) Add, change, remove or list the disk systems. The disk system defines the disk buffer to be used for CTA archive and retrieval operations for each VO. It corresponds to a specific directory tree on a disk instance space (specified using a regular expression). Backpressure can be configured separately for each disk system (how much free space should be available before processing a batch of retrieve requests; how long to sleep when the disk is full). .TP drive (dr) Bring tape drives up or down, list tape drives or remove tape drives from the CTA system. .P .RS \fBcta-admin drive ls\fP displays an exclamation mark (\fB!\fP) in front of the drive name, for drives in DISABLED logical libraries. .RE .TP failedrequest (fr) List and remove requests which failed and for which all retry attempts failed. .TP groupmountrule (gmr) Add, change, remove or list the group mount rules. .TP logicallibrary (ll) Add, change, remove or list the logical libraries, which are logical groupings of tapes and drives based on physical location and tape drive capabilities. A tape can be accessed by a drive if it is in the same physical library and if the drive is capable of reading or writing the tape. In this case, that tape and that drive should normally also be in the same logical library. .TP mediatype (mt) Add, change, remove or list the tape cartridge media types. This command is used to specify the nominal capacity of each media type, which is used to estimate the total capacity of tape pools. Optionally, specify the parameters for software Recommended Access Order (LTO-8 or older tape technology). See \fBcta-taped(1cta)\fP for details. .TP mountpolicy (mp) Add, change, remove or list the mount policies. .TP recycletf (rtf) List tape files in the recycle log. .TP repack (re) Add or remove a request to repack one or more tapes. This command can also list repack requests in progress and display any errors. .TP requestermountrule (rmr) Add, change, remove or list the requester mount rules. .TP showqueues (sq) Show the status of all active queues. .TP storageclass (sc) Add, change, remove or list the storage classes. Storage classes are associated with directories, to specify the number of tape copies for each file, and the corresponding tape pool that each copy should be archived to. In EOS, the storage class is added as an extended attribute of the directory, which is inherited by the file at creation time. .TP tape (ta) Add, change, remove, reclaim, list or label tapes. This command is used to manage the physical tape cartridges in each library. .TP tapefile (tf) List files on a specified tape. \fBcta-admin tapefile ls -l\fP allows listing the disk metadata as well as tape metadata. Use of this option requires that gRPC is correctly configured on the disk system. See \fBFILES\fP, below. .TP tapepool (tp) Add, change, remove or list tape pools. Tape pools are logical sets of tapes which are used to manage the tape lifecycle: label -> supply -> user pool -> erase -> label. \fBcta-admin tapepool ls\fP shows statistics such as the total number of tapes in the pool and number of free tapes. .TP version (v) Display the version of \fBcta-admin\fP, the CTA Frontend, the protocol buffer used for client/server communication, and the CTA Catalogue schema. .TP virtualorganization (vo) Add, change, remove or list the Virtual Organizations (VOs). Each VO corresponds to an entity whose data transfers should be managed independently of the others, for example an experimental collaboration. .SH OPTIONS .TP --json Some commands, such as \fBcta-admin tapefile ls\fR, can return an arbitrarily long list of results, which are normally returned in plain text format, with one record per line. If the --json option is supplied, the results are returned as an array of records in JSON format. This option is intended for use by scripts to ease automated processing of results. .TP --config This option is intended for users who want to specify the location of the config file as an argument in the cli. If the option is not provided, the script will look for the config file ~/.cta/cta-cli.conf. The default config file /etc/cta/cta-cli.conf is used if the user does not provide one. .SH CONFIGURATION The \fBcta-admin\fP configuration is specified in \fI/etc/cta/cta-cli.conf\fR. The following configuration options are available: .TP cta.endpoint (mandatory) Specifies the CTA Frontend hostname (FQDN) and TCP port. .TP cta.resource.options (default: \fInone\fR) Currently the only supported option is \fIReusable\fR. For an explanation of XRootD SSI reusable resources, see: \fIhttp://xrootd.org/doc/dev49/ssi_reference-V2.htm#_Toc506323429\fR .TP cta.log (default: \fInone\fR) Sets the client log level (see \fBXrdSsiPbLogLevel\fR below). .TP cta.log.hiRes (default: \fIfalse\fR) Specify whether log timestamps should have second (\fIfalse\fR) or microsecond (\fItrue\fR) resolution. .SH EXIT STATUS \fBcta-admin\fP returns 0 on success. If there is an error, a message will be printed on \fIstderr\fR. XRootD errors, protocol buffer errors and CTA Frontend errors return exit code 1. User errors (e.g. invalid tape pool or VID) return with exit code 2. In the case of user errors, when the --json option is specified, \fBcta-admin\fP will return an empty JSON array to \fIstdout\fR in addition to the error message printed on \fIstderr\fR. Scripts using \fBcta-admin\fP should interpret the error code to determine whether valid parameters were used. .SH ENVIRONMENT .TP XrdSecPROTOCOL Sets the XRootD security protocol to use for client/server connections. Note that the CTA Frontend enforces the use of the \fIkrb5\fR protocol. Admin commands sent using a different security protocol will be rejected. .TP XrdSsiPbLogLevel Set the desired log level (default: \fInone\fR). Logging is sent to stderr. Available log levels are: \fInone\fR \fIerror\fR \fIwarning\fR \fIinfo\fR \fIdebug\fR There are two additional debugging flags to expose details of the communication between client and server: \fIprotobuf\fR shows the contents of the Google Protocol buffers used for communication in JSON format \fIprotoraw\fR shows the serialized Google Protocol buffer, i.e. the binary format sent on the wire Log level \fIall\fR is a synonym for "\fIdebug\fR \fIprotobuf\fR \fIprotoraw\fR". .TP XRDDEBUG If the XRootD environment variable XRDDEBUG=1, the log level is set to \fIall\fR (see above). .TP XrdSecDEBUG If the XRootD environment variable XrdSecDEBUG=1, authentication messages are logged. This is useful for debugging problems with Kerberos or SSS authentication. .TP XRDSSIDEBUG If the XRootD environment variable XRDSSIDEBUG=1, debug messages will be displayed for each low-level SSI event. .TP XRD_REQUESTTIMEOUT (default: \fI1800\fR seconds) Sets a limit on the time for the entire request to be processed: connection to load balancer + redirection + connection to data server + request/response round-trip. Normally this should be less than one second, but for a heavily-loaded system can take more than one minute. The same timeout is also applied to the response for list commands. List commands can return arbitrarily long output, but by using the XRootD SSI stream mechanism, the timeout is applied to each packet of the response rather than the total time taken to process the response. .TP XRD_STREAMTIMEOUT Note that the XRootD stream timeout is explicitly disabled by the XRootD server for SSI requests, so this environment variable is \fBnot\fR used. .TP XRD_CONNECTIONRETRY (default: \fI1\fR) By default, if the connection to the CTA Frontend fails for any reason, \fBcta-admin\fP returns immediately with \fB[FATAL] Connection error\fR. XRD_CONNECTIONRETRY and XRD_CONNECTIONWINDOW can be used to configure retry behaviour. Note that Connection Retry is a misnomer as it sets the total number of attempts, not the number of retries. .SH FILES .TP .BI /etc/cta/cta-cli.conf See \fBCONFIGURATION\fP above, and \fI/etc/cta/cta-cli.conf.example\fR. .TP .BI /etc/cta/eos.grpc.keytab gRPC keys for each instance, used by \fBcta-admin tapefile ls\fP to display disk metadata associated with files on tape. The format is one line per disk instance, as follows: .P .RS .nf # disk instance endpoint (host:port) gRPC token eosctaphysics eosctaphysics.cern.ch:50051 bf8d9c49-2eda-40bd-82aa-630a556caf31 .fi .RE .SH BUGS .P When using the --json option, 64-bit integer fields are returned as strings. This is a feature of the Google Protocol Buffers library, to cope with the fact that JavaScript parsers do not have the ability to handle integers with more than 32-bit precision. .SH SEE ALSO .P CERN Tape Archive documentation (\fIhttps://eoscta.docs.cern.ch/\fP) .SH COPYRIGHT .P Copyright © 2022 CERN. License GPLv3+: GNU GPL version 3 or later (\fIhttp://gnu.org/licenses/gpl.html\fP). This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. In applying this licence, CERN does not waive the privileges and immunities granted to it by virtue of its status as an Intergovernmental Organization or submit itself to any jurisdiction.