From 4945ba34e1359dcea7bdf20257baff506504d398 Mon Sep 17 00:00:00 2001 From: Michael Davis <michael.davis@cern.ch> Date: Mon, 27 Jan 2020 14:58:58 +0100 Subject: [PATCH] [doc] Updates cta-admin man page --- cmdline/cta-admin.1cta | 43 ++++++++++++++++++++++-------------------- 1 file changed, 23 insertions(+), 20 deletions(-) diff --git a/cmdline/cta-admin.1cta b/cmdline/cta-admin.1cta index 4d870ff6de..0312d1905b 100644 --- a/cmdline/cta-admin.1cta +++ b/cmdline/cta-admin.1cta @@ -1,5 +1,5 @@ .\" Manpage for cta-admin -.TH cta-admin 1cta "January 2019" "0.1" "The CERN Tape Archive (CTA)" +.TH cta-admin 1cta "January 2020" "1.0" "The CERN Tape Archive (CTA)" .SH NAME cta-admin \- administrative command interface for tape system operators .SH SYNOPSIS @@ -16,7 +16,7 @@ To show the subcommands and options for a specific command, type: .SS Options .TP --json -Some commands, such as \fBcta-admin archivefile ls\fR, can return an arbitrarily long list of results, +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. @@ -27,16 +27,19 @@ admin (ad) Add, change, remove or list the administrators of the system. In order to use cta-admin, users must exist in the administrator list and must authenticate themselves with a valid Kerberos KRB5 credential. .TP -archivefile (af) -List files which have been archived to tape. -.TP archiveroute (ar) Add, change, remove or list the archive routes, which are the policies linking namespace entries to tapepools. .TP +disksystem (ds) +Query and manage the EOS disk system (disk buffer in front of CTA). +.TP drive (dr) Bring tape drives up or down, list tape drives or remove tape drives from the CTA system. .TP +failedrequest (fr) +List and manage requests which failed and for which all retry attempts failed. +.TP groupmountrule (gmr) Add, change, remove or list the group mount rules. .TP @@ -64,9 +67,6 @@ Add, change, remove or list the requester mount rules. showqueues (sq) Show the status of all active queues. .TP -shrink (sh) -Shrink a tapepool. -.TP storageclass (sc) Add, change, remove or list the storage classes. Storage classes are associated with directories, to specify the number of tape copies the files in the directory should have. Storage classes should be @@ -76,17 +76,13 @@ 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. +.TP tapepool (tp) Add, change, remove or list the tapepools, which are logical sets of tapes. Tapepools are used to manage the life cycle of tapes (label → supply → user pool → erase → label). Listing the tapepools shows statistics such as the total number of tapes in the pool, number of free tapes, etc. -.TP -test (te) -Test tape read/writes. This is a synchronous command that returns performance stats and errors. It -should be run on an empty self-dedicated drive. -.TP -verify (ve) -Manage tape verification. .SH CONFIGURATION FILE The cta-admin configuration is specified in \fI/etc/cta/cta-cli.conf\fR. The following configuration options are available: @@ -154,20 +150,27 @@ retry behaviour. Note that Connection Retry is a misnomer as it sets the total n number of retries. .\" .SH EXAMPLES .\" Some examples of common usage. +.SH EXIT CODE +cta-admin 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 tapepool or vid) return +with exit code 2. + +In the case of user errors, when the --json option is specified, cta-admin will return an empty JSON array +to \fIstdout\fR in addition to the error message printed on \fIstderr\fR. Scripts using cta-admin should interpret +the error code to determine whether valid parameters were used. .SH SEE ALSO -CTA Administrators' Guide \fIhttps://gitlab.cern.ch/cta/CTA/blob/master/doc/CTA_Admin.pdf\fR +CERN Tape Archive (CTA) Administrator and Operator Guide \fIhttps://tapeoperations.docs.cern.ch/\fR .\" cta-objectstore-list(1), cta-objectstore-dump-object(1) .SH KNOWN BUGS -The --json option only works for commands which have been implemented as XRootD SSI streams. This is -not currently the case for all list commands. -.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 AUTHOR Michael Davis (\fImichael.davis@cern.ch\fR) .SH COPYRIGHT -This program is part of the CERN Tape Archive (CTA). Copyright © 2019 CERN. +This program is part of the CERN Tape Archive (CTA). Copyright © 2020 CERN. .P This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, -- GitLab