Skip to content

Commit 96e6b34

Browse files
HereThereBeDragonsHereThereBeDragons
authored
Update doc for extended attributes (#225)
* change xattr to table and add documentation about multipage attr, add example to restricting xattr access * add missing xattrs in doc * small fixes of typos and better readability
1 parent cab8320 commit 96e6b34

File tree

1 file changed

+85
-118
lines changed

1 file changed

+85
-118
lines changed

‎cpt-details.rst‎

Lines changed: 85 additions & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -661,144 +661,111 @@ information. In general, they can be displayed with a command like
661661

662662
There are the following supported magic attributes:
663663

664-
**catalog\_counters**
665-
Like ``repo_counters`` but only for the nested catalog that hosts the given path.
664+
======================== =======================================================================
665+
**Parameter** **Meaning**
666+
======================== =======================================================================
667+
``catalog_counters`` Like ``repo_counters`` but only for the nested catalog that hosts the given path.
668+
``chunks`` Number of chunks of a regular file.
669+
``chunk_list`` Hashes and sizes of the chunks of a regular (large) file.
670+
``compression`` Compression algorithm, for regular files only. Either "zlib" or "none".
671+
``direct_io`` Indicates if the current entry is using direct IO. Either 0 or 1.
672+
``expires`` Shows the remaining lifetime of the mounted root file catalog in minutes.
673+
``external_file`` Indicates if a regular file is an external file or not. Either 0 or 1.
674+
``external_host`` Like ``host`` but for the host settings to fetch external files.
675+
``external_timeout`` Like ``timeout`` but for the host settings to fetch external files.
676+
``fqrn`` Shows the fully qualified repository name of the mounted repository.
677+
``hash`` Shows the cryptographic hash of a regular file as listed in the file catalog.
678+
``hitrate`` Shows overall cache hitrate since mounting the repository.
679+
``host`` Shows the currently active HTTP server.
680+
``host_list`` Shows the ordered list of HTTP servers.
681+
``inode_max`` Shows the highest possible inode with the current set of loaded catalogs.
682+
``lhash`` Shows the cryptographic hash of a regular file as stored in the local cache, if available.
683+
``logbuffer`` Shows system log messages for the repository.
684+
``maxfd`` Shows the maximum number of file descriptors available to file system clients.
685+
``ncleanup24`` Shows the number of cache cleanups in the last 24 hours.
686+
``nclg`` Shows the number of currently loaded nested catalogs.
687+
``ndiropen`` Shows the overall number of opened directories.
688+
``ndownload`` Shows the overall number of downloaded files since mounting.
689+
``nioerr`` Shows the total number of I/O errors encountered since mounting.
690+
``nopen`` Shows the overall number of ``open()`` calls since mounting.
691+
``pid`` Shows the process ID of the CernVM-FS Fuse process.
692+
``proxy`` Shows the currently active HTTP proxy.
693+
``proxy_list`` Shows all registered proxies for this repository. Also contains fallback proxies. If none are used it shows ``DIRECT``.
694+
``proxy_list_external`` Shows all registered proxies used for accessing external data. If none are used it shows ``DIRECT``.
695+
``pubkeys`` The loaded public RSA keys used for repository whitelist verification.
696+
``rawlink`` Shows unresolved variant symbolic links; only accessible from the root attribute namespace (use `attr -Rg rawlink`).
697+
``repo_counters`` Shows the aggregate counters of the repository contents (number of files etc.)
698+
``repo_metainfo`` Shows the :ref:`repository meta info <sct_metainfo>` file, if available
699+
``revision`` Shows the file catalog revision of the mounted root catalog, an auto-increment counter increased on every repository publish.
700+
``root_hash`` Shows the cryptographic hash of the root file catalog.
701+
``rx`` Shows the overall amount of downloaded kilobytes.
702+
``speed`` Shows the average download speed.
703+
``tag`` The configured repository tag.
704+
``timeout`` Shows the timeout for proxied connections in seconds.
705+
``timestamp_last_ioerr`` Shows the timestamp when the last IO error occured.
706+
``timeout_direct`` Shows the timeout for direct connections in seconds.
707+
``uptime`` Shows the time passed since mounting in minutes.
708+
``useddirp`` Shows the number of currently open directories.
709+
``usedfd`` Shows the number of file descriptors currently issued to file system clients.
710+
``version`` Shows the version of the loaded CernVM-FS binary.
711+
======================== =======================================================================
666712

667-
**chunks**
668-
Number of chunks of a regular file.
669-
670-
**chunk\_list**
671-
Hashes and sizes of the chunks of a regular (large) file.
672-
673-
**compression**
674-
Compression algorithm, for regular files only. Either "zlib" or "none".
675-
676-
**expires**
677-
Shows the remaining lifetime of the mounted root file catalog in
678-
minutes.
679-
680-
**external\_file**
681-
Indicates if a regular file is an external file or not. Either 0 or 1.
682-
683-
**external\_host**
684-
Like ``host`` but for the host settings to fetch external files.
685-
686-
**external\_timeout**
687-
Like ``timeout`` but for the host settings to fetch external files.
688-
689-
**fqrn**
690-
Shows the fully qualified repository name of the mounted repository.
691-
692-
**hash**
693-
Shows the cryptographic hash of a regular file as listed in the file
694-
catalog.
695-
696-
**host**
697-
Shows the currently active HTTP server.
698-
699-
**host\_list**
700-
Shows the ordered list of HTTP servers.
701-
702-
**inode\_max**
703-
Shows the highest possible inode with the current set of loaded
704-
catalogs.
705-
706-
**lhash**
707-
Shows the cryptographic hash of a regular file as stored in the
708-
local cache, if available.
709-
710-
**logbuffer**
711-
Shows system log messages for the repository.
712-
713-
**maxfd**
714-
Shows the maximum number of file descriptors available to file
715-
system clients.
716-
717-
**ncleanup24**
718-
Shows the number of cache cleanups in the last 24 hours.
719-
720-
**nclg**
721-
Shows the number of currently loaded nested catalogs.
722-
723-
**ndiropen**
724-
Shows the overall number of opened directories.
725-
726-
**ndownload**
727-
Shows the overall number of downloaded files since mounting.
728-
729-
**nioerr**
730-
Shows the total number of I/O errors encountered since mounting.
731-
732-
**nopen**
733-
Shows the overall number of ``open()`` calls since mounting.
734-
735-
**pid**
736-
Shows the process ID of the CernVM-FS Fuse process.
737-
738-
**proxy**
739-
Shows the currently active HTTP proxy.
740-
741-
**pubkeys**
742-
The loaded public RSA keys used for repository whitelist verification.
743-
744-
**rawlink**
745-
Shows unresolved variant symbolic links; only accessible from the
746-
root attribute namespace (use `attr -Rg rawlink`).
747-
748-
**repo\_counters**
749-
Shows the aggregate counters of the repository contents (number of files
750-
etc.)
751-
752-
**repo\_metainfo**
753-
Shows the :ref:`repository meta info <sct_metainfo>` file, if available
754-
755-
**revision**
756-
Shows the file catalog revision of the mounted root catalog, an
757-
auto-increment counter increased on every repository publish.
713+
Extended attributes can be queried using the ``attr`` command. For
714+
instance, ``attr -g hash /cvmfs/atlas.cern.ch/ChangeLog`` returns the
715+
cryptographic hash of the file at hand. The extended attributes are used
716+
by the ``cvmfs_config stat`` command in order to show a current overview
717+
of health and performance numbers.
758718

759-
**root\_hash**
760-
Shows the cryptographic hash of the root file catalog.
719+
Multipage Extended Attributes
720+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
761721

762-
**rx**
763-
Shows the overall amount of downloaded kilobytes.
722+
Some extended attributes can be too large to be presented in a single request.
723+
For this additional commands and output modes are available.
764724

765-
**speed**
766-
Shows the average download speed.
725+
The output mode can either be machine-readable (``~``) or human-readable (``@``). The
726+
machine-readable output is designed to return output that can be easily parsed by a
727+
machine and errors are returned as signals. The human-readable output includes a more
728+
descriptive header, including how many pages are available and instructions how to access
729+
them. Errors are returned as plaintext with possible instructions how to resolve the issue.
767730

768-
**tag**
769-
The configured repository tag.
731+
Furthermore, ``<attr>~?`` and ``<attr>@?`` allow retrieving additional information about the attribute.
732+
At the moment, this consist only of the number of pages the attribute has.
770733

771-
**timeout**
772-
Shows the timeout for proxied connections in seconds.
734+
Different pages of the attribute can be accessed with ``<attr>~<page num>`` and ``<attr>@<page num>``
735+
Pages start at 0.
773736

774-
**timeout\_direct**
775-
Shows the timeout for direct connections in seconds.
737+
The commands also work with single page attributes (page number is 0).
776738

777-
**uptime**
778-
Shows the time passed since mounting in minutes.
739+
======================= =======================================================================
740+
**Parameter** **Meaning**
741+
======================= =======================================================================
742+
``<attr>@?`` Human-readable information about the attribute.
743+
``<attr>~?`` Machine-readable (CSV format) information about the attribute.
744+
``<attr>@<page num>`` Output of the attribute with a descriptive header. Page numbers are starting from 0. Errors are returned as plaintext.
745+
``<attr>~<page num>`` Output of the attribute. Page numbers are starting from 0. Errors are returned as signals.
746+
======================= =======================================================================
779747

780-
**usedfd**
781-
Shows the number of file descriptors currently issued to file system
782-
clients.
783748

784-
**version**
785-
Shows the version of the loaded CernVM-FS binary.
786749

787-
Extended attributes can be queried using the ``attr`` command. For
788-
instance, ``attr -g hash /cvmfs/atlas.cern.ch/ChangeLog`` returns the
789-
cryptographic hash of the file at hand. The extended attributes are used
790-
by the ``cvmfs_config stat`` command in order to show a current overview
791-
of health and performance numbers.
750+
Restricting Access to Extended Attributes
751+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
792752

793753
Access to extended attributes can be restricted in the client config to
794-
``root`` and users with a specific (main) ``gid`` listed by
754+
``root`` (``gid=0``) and users with a specific (main) ``gid`` listed by
795755
``CVMFS_XATTR_PRIVILEGED_GIDS``. Extended attributes to which
796756
this should apply are listed in ``CVMFS_XATTR_PROTECTED_XATTRS``.
797757
Note that those attributes must be listed in their full name, e.g. ``user.fqrn``,
798758
``user.rawlink`` or ``xfsroot.rawlink``. Most of the extended attributes
799759
will have the prefix ``user.``. If uncertain, they can be looked up in the source
800760
code of ``cvmfs/magic_xattr.cc``.
801761

762+
Example: Only users with ``gid=788`` (and ``root``) can access the repository name
763+
764+
::
765+
766+
CVMFS_XATTR_PRIVILEGED_GIDS=788
767+
CVMFS_XATTR_PROTECTED_XATTRS=user.fqrn
768+
802769
Repository Publishing
803770
---------------------
804771

0 commit comments

Comments
 (0)