Skip to content

Commit

Permalink
Update doc for extended attributes (#225)
Browse files Browse the repository at this point in the history 
* 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
  • Loading branch information
@HereThereBeDragons
HereThereBeDragons authored Mar 15, 2024
1 parent cab8320 commit 96e6b34
Showing 1 changed file with 85 additions and 118 deletions.
203 changes: 85 additions & 118 deletions cpt-details.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -661,144 +661,111 @@ information. In general, they can be displayed with a command like

There are the following supported magic attributes:

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

**chunks**
Number of chunks of a regular file.

**chunk\_list**
Hashes and sizes of the chunks of a regular (large) file.

**compression**
Compression algorithm, for regular files only. Either "zlib" or "none".

**expires**
Shows the remaining lifetime of the mounted root file catalog in
minutes.

**external\_file**
Indicates if a regular file is an external file or not. Either 0 or 1.

**external\_host**
Like ``host`` but for the host settings to fetch external files.

**external\_timeout**
Like ``timeout`` but for the host settings to fetch external files.

**fqrn**
Shows the fully qualified repository name of the mounted repository.

**hash**
Shows the cryptographic hash of a regular file as listed in the file
catalog.

**host**
Shows the currently active HTTP server.

**host\_list**
Shows the ordered list of HTTP servers.

**inode\_max**
Shows the highest possible inode with the current set of loaded
catalogs.

**lhash**
Shows the cryptographic hash of a regular file as stored in the
local cache, if available.

**logbuffer**
Shows system log messages for the repository.

**maxfd**
Shows the maximum number of file descriptors available to file
system clients.

**ncleanup24**
Shows the number of cache cleanups in the last 24 hours.

**nclg**
Shows the number of currently loaded nested catalogs.

**ndiropen**
Shows the overall number of opened directories.

**ndownload**
Shows the overall number of downloaded files since mounting.

**nioerr**
Shows the total number of I/O errors encountered since mounting.

**nopen**
Shows the overall number of ``open()`` calls since mounting.

**pid**
Shows the process ID of the CernVM-FS Fuse process.

**proxy**
Shows the currently active HTTP proxy.

**pubkeys**
The loaded public RSA keys used for repository whitelist verification.

**rawlink**
Shows unresolved variant symbolic links; only accessible from the
root attribute namespace (use `attr -Rg rawlink`).

**repo\_counters**
Shows the aggregate counters of the repository contents (number of files
etc.)

**repo\_metainfo**
Shows the :ref:`repository meta info <sct_metainfo>` file, if available

**revision**
Shows the file catalog revision of the mounted root catalog, an
auto-increment counter increased on every repository publish.
Extended attributes can be queried using the ``attr`` command. For
instance, ``attr -g hash /cvmfs/atlas.cern.ch/ChangeLog`` returns the
cryptographic hash of the file at hand. The extended attributes are used
by the ``cvmfs_config stat`` command in order to show a current overview
of health and performance numbers.

**root\_hash**
Shows the cryptographic hash of the root file catalog.
Multipage Extended Attributes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

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

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

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

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

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

**usedfd**
Shows the number of file descriptors currently issued to file system
clients.

**version**
Shows the version of the loaded CernVM-FS binary.

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

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

Example: Only users with ``gid=788`` (and ``root``) can access the repository name

::

CVMFS_XATTR_PRIVILEGED_GIDS=788
CVMFS_XATTR_PROTECTED_XATTRS=user.fqrn

Repository Publishing
---------------------

Expand Down

0 comments on commit 96e6b34

Please sign in to comment.