Changeset View
Changeset View
Standalone View
Standalone View
docs/configuration.rst
.. _swh-fuse-config: | .. _swh-fuse-config: | ||||
Configuration | Configuration | ||||
============= | ============= | ||||
The configuration for the Software Heritage Filesystem resides in the | The configuration for the Software Heritage Filesystem resides in the | ||||
``swh > fuse`` section of the shared `YAML <https://yaml.org/>`_ configuration | ``swh > fuse`` section of the shared `YAML <https://yaml.org/>`_ configuration | ||||
file used by all Software Heritage tools, located by default at | file used by all Software Heritage tools, located by default at | ||||
``~/.config/swh/global.yml``. | ``~/.config/swh/global.yml``. | ||||
The configuration file location is subject to the `XDG Base Directory | The configuration file location is subject to the `XDG Base Directory | ||||
<https://wiki.archlinux.org/index.php/XDG_Base_Directory>`_ specification as | <https://wiki.archlinux.org/index.php/XDG_Base_Directory>`_ specification as | ||||
well as explicitly overridden on the :ref:`command line <swh-fuse-cli>` via the | well as explicitly overridden on the :ref:`command line <swh-fuse-cli>` via the | ||||
``-C/--config-file`` flag. | ``-C/--config-file`` flag. | ||||
The following sub-sections and fields can be used within the `swh > fuse` | The following sub-sections and fields can be used within the ``swh > fuse`` | ||||
stanza: | stanza: | ||||
- ``cache``: | - ``cache``: | ||||
- ``metadata``: where to store the metadata cache, must have either a | - ``metadata``: where to store the metadata cache, must have either a | ||||
``in-memory`` boolean entry or a ``path`` string entry (with the | ``in-memory`` boolean entry set to true or a ``path`` string entry (with the | ||||
zack: maybe "boolean entry set to true or ..." (given true is the only meaningful value here, isn't… | |||||
corresponding disk path) | corresponding disk path). | ||||
- ``blob``: where to store the blob cache, same entries as the ``metadata`` | - ``blob``: where to store the blob cache, same entries as the ``metadata`` | ||||
cache | cache. | ||||
- ``direntry``: how much memory should be used by the direntry cache, | |||||
Done Inline Actions"as a percentage of available RAM" zack: "as a percentage of available RAM" | |||||
specified using a ``maxram`` entry (either as a percentage of available RAM, | |||||
or with disk storage unit suffixes: ``B``, ``KB``, ``MB``, ``GB``). | |||||
- ``web-api``: | - ``web-api``: | ||||
- ``url``: archive API URL | - ``url``: archive API URL | ||||
- ``auth-token``: authentication token used with the API URL | - ``auth-token``: authentication token used with the API URL | ||||
- ``json-indent``: number of spaces used to print JSON metadata files (setting | |||||
it to ``null`` disables indentation). | |||||
If no configuration is given, default values are: | If no configuration is given, default values are: | ||||
- ``cache``: all cache files are stored in ``$XDG_CACHE_HOME/swh/fuse/`` (or | - ``cache``: all cache files are stored in ``$XDG_CACHE_HOME/swh/fuse/`` (or | ||||
``~/.cache/swh/fuse`` if ``XDG_CACHE_HOME`` is not set) | ``~/.cache/swh/fuse`` if ``XDG_CACHE_HOME`` is not set). The direntry cache | ||||
- ``web-api``: default URL is <https://archive.softwareheritage.org/api/1/>, | will use at most 10% of available RAM. | ||||
with no authentication token | - ``web-api``: URL is https://archive.softwareheritage.org/api/1/, with no | ||||
Done Inline Actionss/default// (you already said these are default values at the beginning of the list) zack: s/default// (you already said these are default values at the beginning of the list) | |||||
authentication token | |||||
Done Inline Actionss/set to // zack: s/set to // | |||||
- ``json-indent``: 2 spaces. | |||||
Example | Example | ||||
------- | ------- | ||||
Here is a full ``~/.config/swh/global.yml`` example, showcasing different cache | Here is a full ``~/.config/swh/global.yml`` example, showcasing different cache | ||||
storage strategies (in-memory for metadata and on-disk for blob), using the | storage strategies (in-memory for metadata, on-disk for blob, 20% RAM for | ||||
default Web API service: | direntry), using the default Web API service: | ||||
.. code:: yaml | .. code:: yaml | ||||
swh: | swh: | ||||
fuse: | fuse: | ||||
cache: | cache: | ||||
metadata: | metadata: | ||||
in-memory: true | in-memory: true | ||||
blob: | blob: | ||||
path: "/path/to/cache/blob.sqlite" | path: "/path/to/cache/blob.sqlite" | ||||
direntry: | |||||
maxram: 20% | |||||
web-api: | web-api: | ||||
url: "https://archive.softwareheritage.org/api/1/" | url: "https://archive.softwareheritage.org/api/1/" | ||||
auth-token: null | auth-token: eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMTMxYTQ1My1hM2IyLTQwMTUtO... | ||||
Done Inline ActionsThe example would be more meaningful with an actual (invalid) auth-token, instead of "null". I think the Web API auth token already have an example with an invalid auth token, which you can reuse here. zack: The example would be more meaningful with an actual (invalid) auth-token, instead of "null". I… | |||||
Logging | Logging | ||||
------- | ------- | ||||
The default logging level is set to ``INFO`` and can be configured through the | The default logging level is set to ``INFO`` and can be configured through the | ||||
:ref:`shared command line interface <swh-core-cli>` via the ``-l/--log-level`` | :ref:`shared command line interface <swh-core-cli>` via the ``-l/--log-level`` | ||||
flag. | flag. | ||||
.. code:: bash | .. code:: bash | ||||
$ swh --log-level swh.fuse:DEBUG fs mount swhfs/ | $ swh --log-level swh.fuse:DEBUG fs mount swhfs/ |
maybe "boolean entry set to true or ..." (given true is the only meaningful value here, isn't it?)