FCAPS.ECLASS

Section: eclass-manpages (5)
Updated: Aug 2025
Index Return to Main Contents

NAME

fcaps.eclass - function to set POSIX file-based capabilities

DESCRIPTION

This eclass provides a function to set file-based capabilities on binaries. This is not the same as USE=caps which controls runtime capability changes, often via packages like libcap.

Due to probable capability-loss on moving or copying, this happens in pkg_postinst phase (at least for now).

SUPPORTED EAPIS

7 8

EXAMPLE

You can manually set the caps on ping and ping6 by doing:

pkg_postinst() {
        fcaps cap_net_raw bin/ping bin/ping6
}

Or set it via the global ebuild var FILECAPS:

FILECAPS=(
        cap_net_raw bin/ping bin/ping6
)

FUNCTIONS

fcaps [-o <owner>] [-g <group>] [-m <mode>] [-M <caps mode>] <capabilities> <file[s]>

Sets the specified capabilities on the specified files.

The caps option takes the form as expected by the cap_from_text(3) man page. If no action is specified, then "=ep" will be used as a default.

If the file is a relative path (e.g. bin/foo rather than /bin/foo), then the appropriate path var ($D/$ROOT/etc...) will be prefixed based on the current ebuild phase.

The caps mode is used to set the permission on the file if capabilities were properly set on the file. No change is applied by default.

If the system is unable to set capabilities, it will use the specified user, group, and mode. The user and group default to 0. If mode is unspecified, no change is applied.

For example, "-m u+s" may be used to enable suid as a fallback when file caps are unavailable. This should be used with care, typically when the application is written to handle dropping privileges itself.

fcaps_pkg_postinst

Process the FILECAPS array.

ECLASS VARIABLES

FILECAPS

An array of fcap arguments to use to automatically execute fcaps. See that function for more details.

All args are consumed until the '--' marker is found. So if you have:

        FILECAPS=( moo cow -- fat cat -- chubby penguin )

This will end up executing:

        fcaps moo cow
        fcaps fat cat
        fcaps chubby penguin

Note: If you override pkg_postinst, you must call fcaps_pkg_postinst yourself.

FCAPS_DENY_WORLD_READ (USER VARIABLE)

When set, deny read access on files updated by the fcaps function.

MAINTAINERS

base-system@gentoo.org

REPORTING BUGS

Please report bugs via https://bugs.gentoo.org/

FILES

fcaps.eclass

This document was created by man2html, using the manual pages.
Time: 03:27:00 GMT, August 31, 2025