DEBOPS.SYSFS(5)

NAME
debops.sysfs - Manage kernel /sys filesystem using sysfsutils

SYNOPSIS

debops run service/sysfs [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

sysfs <https://en.wikipedia.org/wiki/Sysfs> is a Linux kernel virtual filesystem, usually mounted at /sys. It provides a file-based interface to the kernel data structures related to hardware and host configuration. The filesystem entries can be manipulated by the sysfsutils package provided by Debian/Ubuntu.

The debops.sysfs Ansible role can be used to configure sysfs attributes in supported environments. It can be used as a standalone role, or a dependent role to configure sysfs on behalf of another Ansible role.

GETTING STARTED

  Default configuration

The sysfs configuration will not be applied by default in a container environment (LXC, OpenVZ), since these environments usually have the /sys filesystem mounted read-only. You can control this using the sysfs__enabled variable.

  Example inventory

To configure the /sys kernel filesystem on a host by the debops.sysfs role, that host needs to be added to the [debops_service_sysfs] Ansible inventory group:

[debops_service_sysfs]
hostname

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.sysfs role:

---
- name: Configure sysfs options
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_sysfs' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  pre_tasks:
    - name: Prepare sysfs environment
      ansible.builtin.import_role:
        name: 'sysfs'
        tasks_from: 'main_env'
      tags: [ 'role::sysfs', 'role::secret' ]
  roles:
    - role: secret
      tags: [ 'role::secret', 'role::sysfs' ]
      secret__directories:
        - '{{ sysfs__secret__directories | d([]) }}'
    - role: sysfs
      tags: [ 'role::sysfs', 'skip::sysfs' ]

DEFAULT VARIABLE DETAILS

Some of debops.sysfs default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  sysfs__attributes

The sysfs__*_attributes default variables hold the configuration of the sysfsutils service, stored in the /etc/sysfs.d/ directory. The variables are lists, with each entry defined as a YAML dictionary.

Dictionaries can be specified as a simple attribute/value form where the dictionary key is a path to a sysfs file, and the dictionary value is the value to set, or can be defined as more complex YAML dictionaries with specific parameters:

name
    Required. The name of the sysfs attribute to configure, usually specified as a filesystem path without the /sys/ prefix.

    This parameter is used as the key when entries from multiple attribute lists are merged together. It's also used as a filename in the /etc/sysfs.d/ directory, with / characters replaced by _, unless the item.filename parameter is used.

    If the item.options parameter is used, the sysfs attribute specified as the name is ignored and can be an arbitrary filename.

value
    Optional. Define the value of a given attribute. If item.options parameter is used, the main value parameter is ignored.

owner
    Optional. Set the "owner" and "group" of a file in the /sys/ filesystem. Specify values supported by the chown command. If the item.options parameter is used, the main owner parameter is ignored.

mode
    Optional. Set the file attributes of a file in the /sys/ filesystem. Specify values supported by the chmod command. Make sure to quote the numerical values like 0660, otherwise they will be interpreted by Ansible as octal and may result in unexpected behaviour. If the item.options parameter is used, the main mode parameter is ignored.

filename
    Optional. A custom filename of the configuration file in /etc/sysfs.d/ directory. The .conf suffix is automatically appended.

comment
    Optional. A string or YAML text block with a comment included in the configuration file.

state
    Optional. Control the state of the generated configuration file.

    If not specified or present, the configuration file will be generated.

    If absent, an existing configuration file will be removed.

    If ignore, a given entry is ignored by Ansible during configuration merge, this can be used to conditionally enable or disable configuration entries.

    If defined, a given entry is defined during configuration merge, but it won't change the state of the configuration file on the managed hosts. This state is useful mostly in the role default variables to define sysfs attributes which can be conditionally enabled from inventory or by other Ansible roles.

    If comment, the configuration file will be generated, but all attributes will be commented out. This can be used to create example configuration files.

options
    Optional. YAML list of sysfs attributes with the same format as the one defined above. This parameter can be used to define multiple attributes in the same file. Supported parameters: name, state, value, owner, mode, comment.

  Examples

Define the example configuration from the /etc/sysfs.conf as the role configuration:

sysfs__attributes:
  - name: 'devices/system/cpu/cpu0/cpufreq/scaling_governor'
    comment: 'Always use the powersave CPU frequency governor'
    value: 'powersave'
  # Multiple attributes in one file
  - name: 'userspace_cpufreq_governor'
    comment: |
      Use userspace CPU frequency governor and set initial speed
    options:
      - name: 'devices/system/cpu/cpu0/cpufreq/scaling_governor'
        value: 'userspace'
      - name: 'devices/system/cpu/cpu0/cpufreq/scaling_setspeed'
        value: 600000
  - name: 'power/state'
    comment: 'Set permissions of suspend control file'
    mode: '0600'
    owner: 'root:power'

AUTHOR
Maciej Delmanowski

COPYRIGHT
2014-2024, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others