Skip to content

smoeding/puppet-file_capability

Repository files navigation

file_capability

Build Status Puppet Forge License

Table of Contents

  1. Overview
  2. Module Description - What the module does and why it is useful
  3. Setup - The basics of getting started with file_capability
  4. Usage - Configuration options and additional functionality
  5. Reference - An under-the-hood peek at what the module is doing and how
  6. Limitations - OS compatibility, etc.
  7. Development - Guide for contributing to the module

Overview

Manage file capabilities on Linux.

Module Description

Linux capabilities provide a more fine-grained privilege model than the traditional privileged user (root) vs. non-privileged user model. File capabilities associate capabilities with an executable and grant additional capabilities to the process calling the executable (similar to what a setuid binary does in the traditional model).

This module provides the file_capability type to set or reset file capabilities for a file. See the capabilities(7) man page for details about the available capabilities in your operating system.

Setup

What file_capability affects

  • Sets or resets file capabilities for a given file using the setcap and getcap binaries provided by the operating system.

Setup requirements

  • No additional Puppet modules are required for this type.

Usage

Initialize the class to install the required package

include file_capability

On Debian based operating systems this will install the libcap2-bin package to ensure the required binaries are available. For RedHat based systems the package libcap will be installed instead.

Set a single capability

Set the capability used by ping to be able to open a raw socket without being setuid:

file_capability { '/bin/ping':
  ensure     => present,
  capability => 'cap_net_raw=ep',
}

Set multiple capabilities

This set of capabilities is used by Wireshark to be available to non-root users:

file_capability { '/usr/bin/dumpcap':
  capability => [ 'cap_net_admin=eip', 'cap_net_raw=eip', ],
}

Both capabilities use the same flags, so this can be abbreviated:

file_capability { '/usr/bin/dumpcap':
  capability => 'cap_net_admin,cap_net_raw=eip',
}

Clear all capabilities

Remove all file capabilities:

file_capability { '/path/to/executable':
  ensure => absent,
}

Use hiera to create resources

The main class uses the file_capabilities hash parameter to create file_capability resources. So the following hiera item will create the same resource that is shown in the first example:

file_capability::file_capabilities:
  '/bin/ping':
    ensure:     present
    capability: 'cap_net_raw=ep'

Reference

See REFERENCE.md

Limitations

The type uses a regular expression to validate the capability parameter. Unfortunately some illegal specifications are not caught by this check.

The module is currently developed and tested on:

  • Debian 11 (Bullseye)

Development

Feel free to send pull requests for new features.

About

Manage Linux file capabilities with Puppet

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published