file_capability

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
   • What file_capability affects
   • Setup requirements
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.

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

• The setcap and getcap executables must be available. On Debian these are provided by the libcap2-bin package. The package is not managed by this module.
• No additional Puppet modules are required for this type.

Usage

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,
}

Reference

Type: file_capability

Parameters for the file_capability type:

ensure

Indicate if the capability for the file should be created or removed. Valid options: present, absent. Default value: present

file

The name of the file for which the capabilities should be managed. This must be an absolute pathname. The resource title is used if this parameter is left unspecified.

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

If Puppet manages the file specified by the file parameter, then this type will autorequire the file resource.

capability

A String or an array of strings with capability specifications. A capability specification has the following format:

• A single capability name or a list of capability names separated by commas
• An operator character: =, + or -
• Operator flags using one or multiple lowercase letters: e, i and p

Valid capability specifications are for example:

• 'cap_net_raw=ep'
• 'cap_net_admin,cap_net_raw=eip'
• [ 'CAP_DAC_READ_SEARCH=ep', 'CAP_SYS_ADMIN=ep', ]

See the capabilities(7) manpage for details and a description of all available capabilities and the meaning of the operator flags.

An error is signaled if the capability specification has an illegal format.

Limitations

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

Capabilities are only available on recent operating system releases like RedHat 7 and Debian 8. In addition the file system must support extended attributes to store the capabilities for the file.

The module is currently developed and tested on:

• Debian 8 (Jessie)

Development

Feel free to send pull requests for new features.

2018-02-04 - Release 1.0.1

Summary

A metadata update without functional changes.

2016-10-11 - Release 1.0.0

Summary

Initial release.