# Introduction

grsecurity is a set of patches for the Linux kernel with an emphasis on enhancing security. Its typical application is in web servers and systems that accept remote connections from untrusted locations, such as systems offering shell access to its users.
Released under the GNU General Public License, grsecurity is free software.

## History

Work on grsecurity began in February 2001 as a port of Openwall Project's security-enhancing patches for Linux 2.4. The first release of grsecurity was for Linux 2.4.1.

## PaX

A major component bundled with grsecurity is PaX, which is a patch that, amongst other things, flags data memory, such as that on the stack, as non-executable, and program memory as non-writable. The aim is to prevent executable memory pages from being overwritten with injected machine code, which prevents exploitation of many types of security vulnerabilities, such as buffer overflows. PaX also provides address space layout randomization (ASLR), which randomizes important memory addresses to hinder attacks that rely on such addresses being easily known. PaX is not itself developed by the grsecurity developers, and is also available independently from grsecurity .

## Role-based Access Control

Another notable component of grsecurity is that it provides a full role-based access control (RBAC) system. RBAC is intended to restrict access to the system further than what is normally provided by Unix access control lists, with the aim of creating a fully least-privilege system, where users and processes have the absolute minimum privileges to work correctly and nothing more. This way, if the system is compromised, the ability by the attacker to damage or gain sensitive information on the system can be drastically reduced. RBAC works through a collection of "roles". Each role can have individual restrictions on what they can or cannot do, and these roles and restrictions form a "policy" which can be amended as needed.

## Chroot Restrictions

grsecurity restricts chroot in a variety of ways to prevent a variety of vulnerabilities, privilege escalation attacks, and to add additional checks and balances.
Chroot Modifications:
* No attaching shared memory outside of chroot
* No kill outside of chroot
* No ptrace outside of chroot (architecture independent)

## Miscellaneous Features

grsecurity also adds enhanced auditing to the Linux kernel. It can be configured to audit a specific group of users, audit mounts/unmounts of devices, changes to the system time and date, chdir logging, amongst other things. Some of these other things allow the admin to also log denied resource attempts, failed fork attempts, and exec logging with arguments.
Trusted path execution is another optional feature that can be used to prevent users from executing binaries that are not owned by the root user, or are world-writable. This is useful to prevent users from executing their own malicious binaries or accidentally executing system binaries that could have been modified by a malicious user (being world-writable).
grsecurity also hardens the way chroot "jails" work. A chroot jail can be used to isolate a particular process from the rest of the system, which can be used to minimise the potential for damage, should the service be compromised. However, there are ways to "break out" of a chroot jail. grsecurity attempts to prevent this.
There are also other features that increase security and prevent users from gaining unnecessary knowledge about the system, such as restricting the dmesg and netstat commands to the root user .
List of additional features and security improvements:
* /proc restrictions that don't leak information about process owners
* Symlink/hardlink restrictions to prevent /tmp races
* Hardlink restrictions to prevent users from hardlinking to files they do not own
* FIFO/Named pipe restrictions
* dmesg(8) restriction
* Enhanced implementation of Trusted Path Execution
* Group-based socket restrictions
This book uses many different terms, some of which have the same meaning. We have listed some of these terms and their definitions here. The book also contains inline links to relevant Wikipedia articles.

### access control list

    From a related Wikipedia article: "An access control list (ACL) is a list of permissions attached to an object. The list specifies who or what is allowed to access the object and what operations are allowed to be performed on the object." In the context of this book, an ACL is used to mean a single role or subject definition, or the whole policy file.

### domain

    With domains you can combine users that do not belong in the same group as well as groups so that they share a single policy. Domains work just like roles.

### object

    An object is a part of the system that is used by the programs running on the system. It can be an absolute path to a file or a directory; a capability; a system resource; a PaX flag; network access (IP ACLs).

### policy

    The policy is a system-wide set of rules enforced by grsecurity. A very good description is offered in the mandatory access control article: "Any operation by any subject on any object will be tested against the set of authorization rules (a.k.a. policy) to determine if the operation is allowed."

### role

    A role is an abstraction that encompasses traditional users and groups that exist in Linux distributions and special roles that are specific to grsecurity. Roles can be used to split the responsibility of system administration into smaller logical sets of responsibilities, such as "database administrator" or "DNS administrator". Compare this approach to having a single superuser (e.g. root) that is used to do every administrative task on the system.

### ruleset

    Ruleset is used much in the same way as "access control list". It is perhaps more often used to refer to role or subject definitions than the whole policy file.

### subject

    A subject uses and accesses objects and the ruleset of the subject enforces what objects it may use and in what way. In practice a subject is most often a program running on the system. In grsecurity, a subject is defined as an absolute path to the actual program executable (e.g. /sbin/init) or a directory (e.g. /lib/hal/scripts).
Grsecurity/Typographic Conventions

# Installation

The following instructions will lead you through the process of downloading all the components necessary for using grsecurity on your system. Download each component to the same directory on your computer.
You need:
* The latest stable version of grsecurity.
* A matching version of gradm, the administration utility for grsecurity.
* Full source code of the Linux kernel.
You also need to have necessary programs for building, configuring and installing a custom kernel for your system. The preferred way, and required tools, to do the installation depend on the Linux distribution you are using. If you encounter problems with configuring or installing the kernel, please consult your distribution's documentation.

## Downloading grsecurity

Point your browser to http://grsecurity.net/. Click on the "Download" link and then select a "Stable" or "Test" patch (since September 9th, 2015, stable patches of grsecurity are available to commercial customers only). For the purposes of this document, we will be installing the latest stable grsecurity for kernel 3.2.50. Therefore the patch file will be called "grsecurity-2.9.1-3.2.50-201308052151.patch".
In our case we downloaded the following files
* grsecurity-2.9.1-3.2.50-201308052151.patch
* grsecurity-2.9.1-3.2.50-201308052151.patch.sig - This is the digital signature of this release.

## Downloading gradm

When downloading gradm, the administration utility for grsecurity's role-based access control system, you must download the version that matches the version of the grsecurity patch you downloaded. Gradm is located on the same download page as grsecurity.
In our case we downloaded the following files
* gradm-2.9.1-201308021745.tar.gz
* gradm-2.9.1-201308021745.tar.gz.sig - This is the digital signature of this release.

## Downloading the Linux Kernel

The grsecurity patches can only be applied to a vanilla kernel. Many distributions modify the official kernel with additional patches, which means that any kernel source packages acquired through their package manager is very likely incompatible with grsecurity.
For this reason we will download the official unmodified kernel from http://www.kernel.org/. Download the full kernel source package and its signature (the ".sign" file), and make sure its version matches the version of the grsecurity patch you downloaded. In this document the version is 3.2.50. The required version is most likely not the latest, so you need to get it from the kernel archives.
* Official support for kernel version 2.6.32.61 closed at the end of 2013.
If you've got a terminal open, you can use the below commands to download both the kernel source and the signature to the current working directory:
NOTE: The versions of the grsecurity patch and the kernel must match exactly.

## Verifying the Downloads

The grsecurity and gradm packages have been cryptographically signed so that users can verify that the source code has not been modified since it was packaged. You can find the public key used to sign them from the same download page as grsecurity. Scroll down the page until you see a heading that says "Verify these downloads with GPG". Below the heading is a link to the public key. Download the key to the directory where you placed grsecurity.
Before you can verify the downloads, you need to import the grsecurity key to your public keyring using Gnu Privacy Guard (GPG). If you are unfamiliar with GPG and wish to know more, please refer to The GNU Privacy Handbook.
To import the key, run the following command in the directory where your grsecurity and its key were downloaded.
After importing the key, verify the downloaded grsecurity and gradm packages by running the below commands in your grsecurity directory:
Below is an example of a failed signature verification. The patch file was modified on purpose to make the verification fail.
As long as GPG reports the signature is good, you do not need to worry about the warning about the key not being certified with a trusted signature. If you signed the grsecurity key with your own key, you will not get the warning. If the verification of either file failed (i.e. if you get the "BAD signature" message), re-download the file in question and try again.
The Linux kernel source packages have been signed as well. Please follow the instructions on the Linux kernel website to verify the kernel source package.
When you have successfully verified the downloaded files, you are ready to configure grsecurity.
The following instructions will lead you through the process of patching the Linux kernel with grsecurity, configuring its features and compiling, and installing the patched kernel.

## Patching Your Kernel with grsecurity

In this document the kernel source archive is called linux-3.2.50.tar and the matching grsecurity patch grsecurity-2.9.1-3.2.50-201308052151.patch. Both files are in the same directory.
Change to the root user and run the following commands in the directory you downloaded the files to. The first command decompresses the Linux source package, and the second one applies the patch to the kernel. You may need to install the patch program with your preferred package management tool.

## Configuring the Kernel

The kernel source package contains a generic configuration file that should work without any significant modifications. Your distribution may have its own process and tools for configuring and building the kernel, in which case you should consult their documentation. Nonetheless you should go through the options and make sure they match your hardware and current setup.
To configure the kernel using the default configuration as a base, change into the kernel source directory (e.g. /usr/src/linux-3.2.50), and execute the below command.
You may need to install missing packages and libraries - follow the error messages for direction.
The interactive Kernel Configuration menu will launch. In the 3.x and 2.6 kernels the grsecurity options are under Security options » Grsecurity. Detailed descriptions of each option and its effects on the system can be viewed online on the Grsecurity and PaX Configuration Options page or by using the built-in help functionality of the kernel configuration system. Make sure you understand each option before you enable or disable them. Once you have exited the Configuration menu, you can launch it again by rerunning "make menuconfig".
It is recommended that you start by setting the Configuration Method option to Automatic and then configuring Usage Type and other options to fit your environment and needs. You can fine-tune all grsecurity and PaX settings in the Customize Configuration section, if needed.

### Suggestions

* Enable the sysctl interface (Grsecurity » Customize Configuration » Sysctl Support). It will enable you to change the options that grsecurity runs with, without recompiling the kernel. This is a very helpful feature, especially when you are using grsecurity for the first time. "Configuration Method - Automatic" enables this feature by default.
* Some auditing options produce a lot of log messages, most notably Exec and Chdir logging (GRKERNSEC_EXECLOG and GRKERNSEC_AUDIT_CHDIR, respectively). If you enable either of them, make sure your logging system is properly configured to prevent the logs from flooding. Check Grsecurity » Customize Configuration » Logging Options as well.

## Compiling and Installing the Kernel
### On Debian and Ubuntu

To compile the kernel and build a Debian package (deb), execute the below commands in the kernel source directory. Ubuntu users should reference the Ubuntu Community Page and decide whether they wish to use the ubuntu-package overlay directory in building. For building on Maverick from a git checkout, see How to compile a Ubuntu 10.10 kernel
To install the newly created Debian package, run:
For more information about building kernels in Debian, please refer to the Debian Linux Kernel Handbook.

### Other Distributions

* Gentoo Linux: Gentoo Linux (x86) Handbook and Hardened Gentoo
* CentOS: http://wiki.centos.org/HowTos/Custom_Kernel
* Fedora (release 8 and later): http://fedoraproject.org/wiki/Docs/CustomKernel

### Compilation Differences

As you are compiling a kernel patched with grsecurity, you will notice some differences. One of these differences appears towards the end of compilation, and may look similar to:
This warning is harmless. As described by the PaX Team on the grsecurity mailing list:
You will also notice additional warnings emitted by the compiler when compiling a kernel patched with grsecurity. This is due to additional warning flags that have been added to the build process to help spot specific kinds of bugs. You can ignore these additional warnings.

## Conditional Steps
### Proprietary NVIDIA Driver Patching

If you're using grsecurity on a desktop and plan to use the proprietary NVIDIA drivers, you'll need to patch them to be able to function correctly with grsecurity. To do this, follow these steps:
* Download the NVIDIA driver .run file from NVIDIA's website.
* Download PaX's patch for the NVIDIA driver from https://grsecurity.net/~spender/nvidia-drivers-352.09-pax.patch
* Run sh <name of NVIDIA .run file> -x
* cd `basename <name of NVIDIA .run file> .run`
* patch -p1 < ../nvidia-drivers-352.09-pax.patch
* Install the driver by running ./nvidia-installer

# Administration

Gradm, the administration utility for the role-based access control system, is a powerful tool that parses your ACLs (Access Control Lists), performs the enforcement of a secure base policy, optimizes the ACLs, as well as handles parsing of the learning logs, merges them with your ACL set and outputs the final ACLs.
Before you install gradm, boot into your patched grsecurity kernel. You can compile gradm in any kernel you wish, but the installation will fail if the kernel does not support grsecurity.

## Installation

If your Linux distribution provides ready-made grsecurity kernel packages, they will very likely provide a package for gradm too. If that is the case you should consider using it before compiling gradm yourself.
Before compiling and installing gradm, make sure you have the following applications installed in your system: lex or flex and byacc or bison. If you need Pluggable Authentication Modules (PAM) support, install the header files for your system; The package containing them will very likely be called libpam-dev or similar.
A note should be added to say that if you are compiling gradm on your default linux kernel without grsecurity support the compile will fail and that you will only be able to compile after you reboot into your new grsecurity enabled kernel.
Change to the directory you downloaded gradm and grsecurity to earlier. In this document the name of the compressed package is gradm-3.1-201503211320.tar.gz. Decompress the package and change to the gradm directory by executing the following commands:
To install gradm with PAM support, as a non-root user run:
NOTE: Look at the output from make. Make sure you do not see a line near the end that says "Unable to detect PAM headers, disabling PAM support." If you do, install the PAM header files and run the make command again.
To install gradm without PAM support, run:
Finally, as root, run:
The installation process does the following:
* Installs the gradm and grlearn programs to /sbin.
* Creates a directory /etc/grsec and two files in it (if they are not already present): learn_config and policy.
* Installs gradm's man pages to /usr/share/man/man8.
* (grlearn does not come with a man page. It is used internally by gradm.)
* Finally, and most importantly, if this is the first time you are installing gradm on your system you will be asked to provide the administrative password for the RBAC system. Choose a long password, but one that you will remember (especially if you start gradm from an initscript). Do not use the same password as your root password.
If you need to change any of the binary or man page locations, modify the Makefile.

## Usage

To display all available command-line switches, run gradm --help.

## Learning Mode

The learning mode is different than anything found in other security systems. Grsecurity's learning mode can be used on a per-subject or per-role basis, as well as system-wide. When using the learning mode on a single process or role, the rest of the system remains protected as defined by the policy. The learning mode can learn all things that the RBAC system supports: files, capabilities, resources, what IP addresses make use of each role, and socket usage. The learning system performs intelligent reduction of filesystem and network access to reduce policy size, increase readability, and reduce the amount of manual tweaking needed later. Furthermore, the learning system enforces a secure base that is configurable. The /etc/grsec/learn_config file gives the administrator the ability to specify files/directories that should be considered protected resources by the learning system. The learning system will ensure that regardless of any rule reduction done, only the processes that access those protected resources through normal usage will be granted access through the generated policy. Furthermore, it will create new subjects for the processes that access the protected resources, creating privilege boundaries that grant those processes additional protection.

### Full System Learning

To enable full system learning, run gradm as root with the following options:
This will enable the Role-based Access Control (RBAC) system and initiate full system learning. That is, gradm will monitor and log what your system does. The log can then be used to build a least privilege policy for your system.
Run and use the application(s) that you normally do, several times. This is important, since the learning mode uses a threshold–based system to determine when access should be given to a file or whether it should be given to a directory. If four or more similar accesses are made in a single directory (such as writing to several files in /tmp), access is granted to that directory instead of the individual files. This reduces the amount of rules you have and ensures that the application will work correctly after the final ACLs are compiled.
* Do not perform any administrative tasks outside of the admin role while full system learning is enabled.
To perform administrative tasks while full system learning is enabled, authenticate to the admin role with:
Remember to exit your shell or unauthenticated from the admin role with gradm -u when you are done performing administrative tasks.
Once you feel you've given the system the normal usage it would see in real life, disable the RBAC system with gradm -D. Disabling RBAC is a necessary step, as it forces the learning daemon to flush its buffers to disk. Using learning logs obtained before RBAC has been disabled will produce incomplete results. Once RBAC is disabled, execute:
This will place the new learned ACLs at the end of your ruleset. You can test the policy by enabling grsecurity (run gradm -E), and making sure all applications are functioning the way they're supposed to.

### Process and Role-Based Learning

Using this learning mode is very simple. All you have to do is add "l" (the small letter L, not the number 1) to the subject mode of the process, you want to enable learning for. To learn all necessary access for a given binary that does not yet have an established policy, add the following subject:
To learn on a given role, add "l" to the role mode. For both of these, to enable learning, enable the system by executing:
When you are done, disable the ACL system with gradm -D (or alternatively, go into admin mode with gradm -a), and use:
This will place the new learned ACLs at the end of your ruleset. Simply remove the old ACLs and you are ready to go.

### /etc/grsec/learn_config

This configuration file aids the learning process by tweaking the learning algorithm for specific files and directories. It accepts lines in the form of:
Where <command> can be inherit-learn, no-learn, inherit-no-learn, high-reduce-path, dont-reduce-path, protected-path, high-protected-path, and always-reduce-path. inherit-learn, no-learn, and inherit-no-learn only affect full system learning, while the others work on all modes of learning.
inherit-learn changes the learning process for the specified path by throwing all learned accesses for every binary executed by the processes contained in the pathname into the subject specified by the pathname. This is useful for cron in the case of full system learning, so that scripts that eventually end up executing mv or rm with privilege don't cause the root policy to grant that privilege to mv or rm in all cases.
no-learn allows processes within the path to perform any operation that normal system usage would allow without restriction. If a process is generating a huge number of learning logs, it may be best to use this command on that process and configure its policy manually.
inherit-no-learn combines the above two cases, such that processes within the specified path will be able to perform any normal system operation without restriction as will any binaries executed by these processes.
high-reduce-path modifies the heuristics of the learning process to weigh in favor of reducing accesses for this path.
dont-reduce-path modifies the heuristics of the learning process so that it will never reduce accesses for this path.
always-reduce-path modifies the heuristics of the learning process so that the path specified will always have all files and directories within it reduced to the path specified.
protected-path specifies a path on your system that is considered an important resource. Any process that modifies one of these paths is given its own subject in the learning process, facilitating a secure policy.
read-protected-path specifies a path on your system that contains sensitive information. Any process that reads one of these paths is given its own subject in the learning process, facilitating a secure policy.
high-protected-path specifies a path that should be hidden from all processes but those that access it directly. It is recommended to use highly sensitive files for this command.
Note that regular expressions are not supported for pathnames in this configuration file.
This page will introduce you to some additional utilities. They are not required to use a grsecurity-enabled system, but are very useful and thus recommended.

## Controlling PaX Flags (paxctl)

Paxctl is a user-space utility for controlling PaX flags of executables (see Appendix/PaX Flags for a list of these flags).

### Installation

Download the latest version from the PaX website at http://pax.grsecurity.net/. In our case we downloaded paxctl-0.7.tar.bz2. Paxctl packages are not signed. Change into the directory you downloaded the package to and run the below commands.
The installation process does the following:
* Installs the paxctl program to /sbin.
* Installs paxctl's man pages to /usr/share/man/man1.
If you need to change either of these locations, modify the Makefile.

### Usage

To display all available command-line switches, run paxctl --help. Read the man page for more detailed information.

### Examples

Lets query what, if any, PaX flags have been enabled for /usr/bin/vi:
As you can see, paxctl could not display the flags because vi does not have the appropriate program header. We need to convert the header and query the flags again.
* Note that paxctl does not make backup copies of the files it modifies. It is recommended that you make backups of the binaries you want to modify.
With the appropriate program header in place, we can query and modify the PaX flags of vi.

## Displaying Program Capabilities (pspax)

The pspax program displays the run-time capabilities of all programs you have permission for. It is part of the pax-utils package. Pax-utils can be found at http://dev.gentoo.org/~vapier/dist/. It contains many useful tools for PaX but is not as critical as paxctl. The pax-utils package is maintained by the Hardened Gentoo Project.
Programs that the pax-utils package provides:
* pspax - Displays the run-time capabilities of all programs you have permission for.
* scanelf - Prints out information specific to the ELF structure of a binary.
* dumpelf - Converts a ELF file into human readable C code that defines a structure with the same image as the original ELF file.
For more information, see the Gentoo Linux guide to pax-utils.

### Installation

Gentoo Linux and Debian GNU/Linux users (and possibly others) can install the pax-utils package the same way they install any other application in their system. Below are instructions on how to compile and install it from the source.
Download the latest version from http://dev.gentoo.org/~vapier/dist/. In our case we downloaded pax-utils-0.4.tar.xz, the latest stable release at the time of writing. Change into the directory you downloaded the package to and run the below commands.
The installation process does the following:
* Installs the pspax, scanelf, dumpelf and scanmacho programs to /usr/bin.
* Installs README, BUGS, and TODO files to /usr/share/doc/pax-utils/.
* Installs man pages of pspax, scanelf and dumpelf to /usr/share/man/man1.
If you need to change any of these locations, modify the Makefile.

### Usage

To display all available command-line switches, run pspax --help. Read the man page for more detailed information.
Pspax shows the PaX flags of a single program as a string of characters (e.g. "peMRS"). Lowercase character means the flag is disabled, uppercase means it is enabled. Below is a table that shows these characters and their corresponding PaX flags used by grsecurity. The "Details" column contains a link to a detailed explanation of each flag.
| pspax flag | grsecurity's PaX flag | Details |
| E | PAX_EMUTRAMP | emutramp.txt |
| M | PAX_MPROTECT | mprotect.txt |
| P | PAX_PAGEEXEC | pageexec.txt |
| R | PAX_RANDMMAP | randmmap.txt |
| S | PAX_SEGMEXEC | segmexec.txt |

### Examples

The command pspax -p <process_id> displays information about a specific process, identified by its PID. It is unlikely that you happen to know or remember the PID of a process, so it is easier to refer to them by name. The below example uses the pidof command to find the PID of a process which it then passes on to pspax:

## Managing the Executable Stack of Binaries (execstack)

Execstack is a tool to set, clear or query executable stack flag of ELF binaries and shared libraries. It is part of the prelink program, but your Linux distribution may provide it as a separate package.

### Installation

You are very likely to find the prelink and/or execstack packages using your distribution's package management system. At least Gentoo, Debian, Red Hat and distributions based on them provide a prelink and/or execstack packages.

### Usage

To display all available command-line switches, run execstack --help. Read the man page for more detailed information. Online version of the man page can be found at http://linux.die.net/man/8/execstack.

### Examples

To check if a library has executable stack enabled, run:
The dash means libcrypto does not require an executable stack. If it did, the line would start with a capital "X" instead of a dash.
To query the status of all libraries in your system, run:

## The sysctl Interface

The sysctl command provides an interface for modifying kernel parameters at runtime. There is an option in the grsecurity kernel configuration to enable support for this interface (see Configuring grsecurity). In Linux, sysctl is simply a wrapper around filesystem routines that read and write contents of files in the /proc directory. This means that you can also set parameters by echoing values to files in /proc. See the Appendix for a list of all available sysctl options for grsecurity.

### Usage

The sysctl command takes a list of variables or variable=value pairs and sets or reads their value. Variable is a path to a file in /proc/sys separated by periods or forward slashes. The value depends on the parameter in question. Most of grsecurity's options are either 1 (enabled) or 0 (disabled).
Sysctl's man page is available online at http://linux.die.net/man/8/sysctl.

### Examples

If you want to know every available runtime option for grsecurity, list the contents of /proc/sys/kernel/grsecurity.
To enable mount auditing and disable chdir auditing in a single sysctl command, run:
You can achieve the same result by echoing:
Grsecurity/Auditing

# Policy Configuration
## What Is an RBAC System?

A role-based access control (RBAC) system is an approach to restricting system access to authorized users. You need an RBAC system if you want to restrict access to files, capabilities, resources, or sockets to all users, including root. This is similar to a Mandatory Access Control (MAC) model. The other features of grsecurity are only effective at fending off attackers trying to gain root, so the RBAC system is used to fill in this gap. Least privilege can be granted to processes, which, in turn, forces attackers to reevaluate their methods of attack, since gaining access to the root account no longer means that they have full access to the system. Access can be explicitly granted to processes that need it, in such a way that root acts as any other user. Though grsecurity and its RBAC system are in no means perfect security, they greatly increase the difficulty of successfully compromising the system.
In grsecurity, the RBAC system is managed through a policy file which is essentially a system-wide set of rules. When the RBAC system is activated with gradm, the policy file is parsed and checked for security holes, such as granting the default role access to certain sensitive devices and files like the policy file itself. If a security hole is found, gradm will refuse to enable the RBAC system, and will give the user a list of things that need to be fixed. The policy file is protected when the RBAC system is active, and only the admin role may access it during that time. To make it easier to create a secure policy, gradm has the ability to learn how the system functions, and build a least-privilege policy based on the collected data (see Learning Mode).

## Limitations of Any Access Control System

So as not to contribute further to the false sense of security many have regarding access control systems (whether they be grsecurity's RBAC, SELinux, RSBAC, SMACK, TOMOYO, AppArmor, etc.) it's important first to describe the limitations of any access control system.
There is a fundamental architectural limitation to the kind of guarantees an access control system can provide when the policy decision-making code resides alongside the Operating System's kernel. A compromise of the Operating System can easily result in compromise of the access control system, and it is common practice for exploits which compromise the kernel to disable any active security systems.
Grsecurity is in no way immune to this fundamental limitation, though it does contain several features to help prevent exploitation of the kernel in the first place and furthermore to make the kernel a more hostile environment to an attacker if they do manage to exploit certain types of bugs. The project will continue to make adding similar protections one of its main goals.
Specifically, the following features are involved in kernel self-protection and increasing the difficulty of kernel exploitation:
There also exist some features of grsecurity which are always active (and thus have no configure-time option) which aid in the above goals. These include the read-only and non-executable vsyscall page (and its shadow page) on amd64, hardening of the BPF interpreter buffers, and many more.
Though these features have been successful at preventing previous vulnerabilities from being exploited (and surely will continue to do so) there have still been many vulnerabilities it did nothing to prevent exploitation of, and there are entire classes of vulnerabilities (such as missing capability checks, some race conditions, etc.) that it can likely never do anything to prevent exploitation of.
It's partially due to this fundamental limitation of any access control system that grsecurity's RBAC system was designed as it was: to be as automated as possible, to provide a sufficient level of access control, to have easily editable human-readable configurations, and to enforce secure base policies to eliminate some administrator error.
Neither grsecurity's RBAC system nor any other access control system should be used to separate classified information from unclassified information on the same machine. There is no virtual replacement for a physical air-gap.

## Policy Structure

The policy is made up of roles, subjects and objects. Role is an abstraction that encompasses traditional users and groups that exist in Linux distributions and special roles, that are specific to grsecurity. Subjects are processes or directories, and objects are ﬁles, capabilities, resources, PaX flags, and IP ACLs. The location of the main policy ﬁle is /etc/grsec/policy.

### Policy Structure in a Nutshell

To see a small example policy, look at the default /etc/grsec/policy file that is installed with gradm. In a nutshell, RBAC policies have the following structure:
Using the default policy as an example:

## Rules for Policies
### Policy generalization

There exist some features of the RBAC system to aid in simplification and generalization of policies. One of these is the recently added "replace" rule. The replace rule allows you to assign a string to a variable, and then use that variable within any subject or object pathname to have it replaced with the string. The syntax of replace rules are:
So for example:
The defined variable can then be used as follows:
The variables defined with replace rules can be reassigned at any location in the policy. All rules in the policy until another redefinition of the variable will use that new assigned value for the variable. For example:
would cause the following object rules to be created:

### Special Cases

There are some special cases you should know about when writing policies for the RBAC system.
There exist some unique accesses to filesystem objects that require specific object modes. For instance, a process that connects to a unix domain socket (/dev/log for example) will need "rw" set as the object mode for that socket.
Adding the setgid or setuid flag to a path requires the "m" object mode.
Creating a hard-link requires at minimum a "cl" object mode. The remaining object flags must match on the target and the source. So for instance, if a process is creating a hard-link from /bin/bash to /bin/bash2, example rules would be:
Creating a symlink requires the "wc" object mode.

### Wildcarded Objects

One very useful feature of the RBAC system is the support of wildcards in objects. The "*" character matches zero or more characters, "?" matches exactly one character, and "" can be used to specify an inclusive or exclusive list or range of characters to match. Depending on how these wildcard characters are used, they have different effects. Here are four examples of the use of wildcards:
The first example would match /dev/ttya, /dev/tty0, /dev/ttyS0, etc. Since a '*' at the end of a path can match the '/' character as well, if a '/dev/tty/somefile' path existed, the first example would match it also.
The second example would match /home/user1/bin, /home/user2/bin, etc. Note that this rule would not match the path /home/user1/test/bin as the wildcard characters will not match '/' unless it appears at the end of a path. To use the particular wildcarded object for this example, a /home object must exist as an "anchor" for the wildcarded object. If you forget to add one, gradm will remind you.
The third example would match /dev/tty0, /dev/tty1,..., /dev/tty9 and nothing else.
The fourth example would match /dev/ttya and /dev/tty0 just like the first example, but would not match /dev/ttyS0 since only one character can match the '?' wildcard.
Wildcards are evaluated at run-time, providing a powerful way of specifying and simplifying policy. Since wildcard matching is based off pathnames and not inode/device pairs though, they aren't intended to be used for objects which are known to be hardlinked at policy enable time.

## Roles

Roles exist essentially as a container for a set of subjects, put to use in specific scenarios. There exist user roles, group roles, a default role, and special roles. See Flow of Matches to see how a role gets matched with a particular process.

### User Roles

In a simplified form, user roles are roles that are automatically applied when a process either is executed by a user of a particular UID or the process changes to that particular UID. In the RBAC system, the name of a user role must match up with the name of an actual user on the system.
A user role looks like:

### Group Roles

As with user roles, group roles pertain to a particular GID. The name of the group role must match up with the name of an actual group on the system. Note that this is tied only to the GID of a process, not to any supplemental groups a process may have. Group roles are applied for a given process only if a user role does not match the process' UID.
A group role looks like:

### Default Role

If neither a user or group role match a given process, then it is assigned the default role. The default role should ideally be a role with nearly no access to the system. It is configured in such a way if full system learning is used.
A default role looks like:

### Special Roles

Special roles are to be used for granting extra privilege to normal user accounts. Some example uses of special roles are to provide an "admin" role that can restart services and edit system configuration files. Special roles can also be provided for regular users to keep their accounts more secure. If they have their own public_html directory, the user role for the user could keep this directory read-only, while a special role to which the user is allowed to transition could allow modification of the files in the directory.
Special roles come in two flavors, ones that require authentication, and ones that do not. On the side of special roles that require authentication, the RBAC system supports a flag that allows PAM authentication to be used for the special role. See Role Modes for a list of all these flags.
Special roles by themselves won't do anything unless there exist non-special (user, group, or default) roles that can transition to them. This transitioning is defined by the role_transitions rule, described in the Role Attributes page.
To authenticate to a special role, use gradm -a <rolename>. To authenticate with PAM to a special role, use gradm -p <rolename>. To transition to a special role that requires no authentication, use gradm -n <rolename>.
Special roles look like:

## Domains

With domains you can combine users that don't share a common group ID as well as groups so that they share a single policy. Domains work just like roles, with the only exception being that the line starting with "role" is replaced with one of the following:
Example:
As it is with user and group roles, all domain members must exist, and if they're not, an error is raised.

## Subjects

Subjects can describe directories, binaries or scripts. Regular expressions are currently not permitted for subjects. The ability to place a subject on a script is unique, as it permits one to grant privilege to a specific script instead of generally to the associated script's interpreter. For this to function properly, make sure the script's interpreter directive does not use #!/usr/bin/env but rather the full path to the interpreter.

## Capability Restrictions

When no capability restriction rules are used for a given subject, all capabilities that the system grants normally to processes within that subject are allowed to be used. An exception to this is if the subject involved uses policy inheritance. In that case, the capability restrictions would come from the subject(s) being inherited from. Capability rules have the form +CAP_NAME or -CAP_NAME. CAP_ALL is a pseudo-capability meant to describe the entire list of capabilities. It's mainly used to remove all capability usage for a subject, or in conjunction with a small number of rules granting the ability to use individual capabilities. Provided below are some example scenarios of capability restriction usage, along with an explanation of how the policy is interpreted.
Scenario #1: In this scenario, we're removing all capabilities from su but CAP_SETUID and CAP_SETGID.
Scenario #2: In this scenario, we're making use of policy inheritance. Note that the default subject allows CAP_NET_BIND_SERVICE and CAP_NET_RAW. In our ping subject, we're removing CAP_NET_BIND_SERVICE, but since we're inheriting from the default subject (note the lack of the o subject mode on the ping subject), we are still allowed CAP_NET_RAW. Granting important capabilities to default subjects is not something allowed by the RBAC system, so this is just an example.
Auditing and Suppression: Auditing of attempted capability use and suppression of denied capability usage is possible as well. Capability auditing and suppression supports the same policy inheritance rules as normal capability rules. The below example demonstrates auditing the use of CAP_NET_RAW and the suppression of CAP_NET_BIND_SERVICE denials:
For a full listing of the capabilities available, see: Capability Names and Descriptions. Note that not all of the capabilities listed may be supported by your particular version of the Linux kernel.

## Resource Restrictions

One of the features of grsecurity's ACL system is process–based resource restrictions. Using this feature allows you to restrict things like how much memory a process can take up, how much CPU time, how many ﬁles it can open, and how many processes it can execute. Also in this section, we will discuss a "fake" resource implemented in grsecurity's ACL system called "RES_CRASH" that helps guard against bruteforce exploit attempts, which is necessary if you're using PaX.
A single resource rule follows the following syntax:
An example of this syntax would be:
This would allow the process to open a maximum of 3 ﬁles (all processes have 3 open ﬁle descriptors at some point: stdin (standard input), stdout (standard output), and stderr (standard error output)).
To clarify what the soft limit and hard limit are, the soft limit is the limit assigned to the process when it is run. The hard limit is the maximum point to which a process can raise the limit via setrlimit(2), unless they have CAP_SYS_RESOURCE. In the case of RES_CPU, when the soft limit is overstepped, a special signal is sent to the process continuously. When the hard limit is overstepped, the process is killed.
A person who is less familiar with Linux should stick to setting limits on the number of ﬁles, the address space limit, and number of processes. Of course, you can always use the learning mode of grsecurity to set the resource limits for you. The RES_CPU resource is the only one that accepts time as limits. The time defaults to units of milliseconds. You can also append a case sensitive unit to your limit.
Some examples would be:
* 100s – 100 seconds
* 25m – 25 minutes
* 65h – 65 hours
* 2d – 2 days
The other resources either operate on a number itself or on a size, in bytes. For these you can use the following units: K, M, and G, like:
* 2G – 2 billion
* 25M – 25 million
* 100K – 100 thousand
If you don't want any restriction for the soft or hard limit for a resource, you can use "unlimited" as the limit. Here are some more examples to help you understand how this works:
For a list of accepted resource names and units, see System Resources.

### RES_CRASH

This "fake" resource limit is expressed by using the name "RES_CRASH" and has the following syntax:
For example, if you wanted to allow the program to crash once every 30 minutes, you would use the following:
What happens when this threshold is reached? Well, the only way to ensure that the process won't crash again is to keep it from being executed. If the process is a suid/sgid binary run by a regular user, we kill all processes of that regular user and keep them from logging in for the amount of time, speciﬁed as the second parameter to the RES_CRASH resource. So for the above example, the user would be locked out of the system for 30 minutes. If the process is not a suid/sguid binary, we simply keep the binary from being run again for the amount of time speciﬁed as the second parameter to the RES_CRASH resource, after killing all processes of that binary.

## Socket Policies

The RBAC system supports policies on what local IP addresses and ports can be reserved on the machine, as well as what remote hosts and ports can be communicated with. These two different accesses are abstracted to bind and connect rules, respectively. The syntax for the rules is:
"proto" can be any of the protocol names listed in /etc/protocol or "any_proto" to denote any protocol. "socket type" is most commonly "ip", "dgram", or "stream", but can also be "raw_sock", "rdm", or "any_sock" to denote any socket type. Most of the parameters for these rules are optional, particularly the netmask and port or port range. If a port is supplied, then at least an IP address of 0.0.0.0/0 needs to be supplied.
As with capability restrictions, resource restrictions, and many other RBAC features, if the socket policies are omitted for a given subject, then the subject is allowed to bind or connect to anything normally allowed by the system. Note though that if a connect rule is given, then at least one bind rule must also be specified. Older versions of gradm (before the 9/16/09 2.1.14 release) will treat the unspecified rule as a "disabled" rule, whereas new versions will generate an error on such policies.
* Unlike with file objects and capabilities, policy inheritance has not been implemented for socket policies. Therefore, the socket policies for a given subject are solely determined by that subject alone.
Here are some example rules:
In this example, ssh is allowed to connect to ssh servers anywhere on the class C 192.168.0.X network. It is also allowed to do DNS lookups through the host specified. The hostname is resolved at the time the RBAC system is enabled.
In this example, netcat is allowed to listen on ports 1024 through 65535 on any local interface for TCP connections. It is also able to connect to TCP port 5190 of the 22.22.22.22 host.
This example illustrates how you can have bind disabled but still specify connect rules, or conversely, have connect disabled and only specify bind rules.
As you can see from the examples above, you can have as many socket policies as you wish for a given subject, and as you'll read below there are some powerful extensions to the socket policies.

### Per-interface Socket Policies

Rules such as:
are allowed, giving you the ability to tie specific socket rules to a single interface (or by using the inverted rules mentioned below, all but one interface). Virtual interfaces are specified by the <ifname>#<vindex> syntax. If an interface is specified, no IP/netmask or host may be specified for the rule.

### Inverted Socket Policies

Rules such as:
are allowed, which allows you to specify that a process can connect to anything except to port 80 of www.google.com with a stream TCP socket. The inverted socket matching also works on bind rules.

## PaX Flags

In more recent versions of the RBAC system, PaX flags have been changed from single-letter subject modes to more closely resemble how capabilities are handled within the policy. Therefore, PaX flags can now be fully controlled on or off for any given subject by adding +PAX_<feature> or -PAX_<feature> within the scope of a subject. For a full listing of the PaX flags available, see: PaX Flags.

## Flow of Matches

Each process on the system has a role and a subject attached to it. This section describes how a process is matched to a role and subject, and how matches are calculated against the objects and capabilities they use. Understanding the flow of matches is necessary for manually creating policies.

### Role Hierarchy

When determining a role for a process, the RBAC system matches based on the following role hierarchy, from most specific to least specific:
Both user and group roles are permitted to have the role_allow_ip attributes. When checking the UID or GID against the user or group role, respectively, the role_allow_ip attributes come into play. Imagine the following policy:
If someone attempted to log in to the machine as user1 from any IP address other than 192.168.1.5, they would not be assigned the user1 role. The matching system would then fall back on trying to find an acceptable group role, or if one could not be found, fall back to the default role.

### Subject/Object Hierarchy

Hierarchy for subjects and objects involves matching a most specific pathname over a less specific pathname. So, if a /bin object exists, and a /bin/ping object exists, and a process is attempting to read /bin/ping, the /bin/ping object would be the one matching. If /bin/su were being accessed instead, then /bin would match.
The path from most specific to least specific pathname isn't linear however, particularly in the case of subjects using policy inheritance. Imagine the following policy:
If /root/test/blah was being accessed by /usr/bin/specialbin, it would not be able to write to it. The reason for this is that when going from most specific to least specific for a given path (which involves stripping off each trailing path component and attempting a match for the resulting pathname), the matching algorithm will look (in order from most specific to least specific) in each of the subjects the current subject inherits from. In this case, the algorithm saw that no object existed for /root/test/blah in the /usr/bin/specialbin subject, so upon checking the subject for / it found a /root/test/blah object, thus resulting in the read-only permission.
When going from most specific to least specific, a globbed object such as /home/* is treated as less specific than /home/blah (if the requested access is for /home/blah). Globbed objects are matched in the order in which they're listed in the RBAC policy. So in the following example:
If a process were accessing /home/testing/somefile it would only be allowed to read it, since the /home/* rule was listed first. It was likely that the policy writer didn't intend this behavior (because the /home/test* rule would never match) so the /home/test* object should be swapped to the line the /home/* object is on.

### Capability Hierarchy

When determining whether a capability is granted or not, the RBAC system works from most specific subject to least specific (in the case of policy inheritance). The first subject along that path that mentions the capability in question is the one that matches. To illustrate:
In this example, /bin/su is able to use only CAP_SETUID and CAP_SETGID. A lookup on CAP_NET_BIND_SERVICE would fall back to the /bin subject, since /bin/su inherits from it and did not explicitly list a rule for CAP_NET_BIND_SERVICE. The /bin subject specifies that CAP_NET_BIND_SERVICE be disallowed. Matching against another capability, CAP_SYS_ADMIN for instance, would end up falling back to the / subject, where it would match -CAP_ALL and be denied.

## Policy Recommendations

Try to remove as many capabilities from default subjects as possible. The more you remove, the closer root comes to acting as a regular user. The more capabilities you remove, however, the more subjects you will have to create for programs that need those capabilities. The RBAC system will enforce that a minimum level of capabilities be removed from all default subjects.
Use full system learning. It will generate a better policy than you would have generated by hand. Make sure you're making full use of the /etc/grsec/learn_config file to specify the files and directories particular to your system that you want protected. gradm will do all the heavy lifting of creating privilege boundaries for processes that access or modify important data.
Administrative programs, such as shutdown or reboot, should require authentication instead of giving everyone the capabilities to run them.
Always inspect your kernel logs. The RBAC system provides a great amount of human-readable information in every kernel log. Of particular importance is what role and subject were assigned to the process causing an alert. If you think that the alert doesn't match up with what you expect from your policy, make sure that the role and subject actually match. If they don't, then you may have issues with a role_allow_ip rule that's preventing the proper role from being applied.
Familiarize yourself with Linux’s capabilities and what they cover. A full listing of them is available here: Capability Names and Descriptions.
Avoid using policy inheritance until you understand fully how it forms the policy for a given subject. Even then, use it sparingly, reserving it generally for cases where a default subject is configured least privilege, with no readable/writable/executable objects and no capabilities.
Wherever possible, avoid granting both write and execute permission to objects. This gives a potential attacker the ability to execute arbitrary code. Similar to how PaX prevents arbitrary code execution within a given process' address space, one of your goals in creating policies is to prevent this on the file system as well.
Be careful using the suppression ('s') object flag, especially when applying it to / to ignore accesses a program does not really need to operate correctly. A change in glibc or another library the subject uses could cause the application to fail in a way that will be difficult to debug (unless your first step is to remove the suppression flag).

## Sample Policies

Below is the sample policy provided with a gradm installation:
Below is a full user role policy that covers the behavior of cvs-pserver when run as the non-root cvs user, providing anonymous read-only CVS repository access.
Here's all that's needed for an unprivileged sshd account:

# Application-specific Settings

This page lists applications that need specific settings to work with grsecurity and PaX. If you wish to add an application to the list, you are most welcome to do so. Please keep the list in alphabetical order and remember to update the table of contents on the front page.

## ATI Catalyst (fglrx) graphics driver

When using Xorg and the proprietary ATI Catalyst graphics driver, CONFIG_PAX_USERCOPY must not be set as PAX_USERCOPY prevents a real overflow from occurring in the ATI driver that is still unfixed. This is in addition to what's shown in the section on Xorg below.
As of 11.8, CONFIG_PAX_MEMORY_UDEREF must also be disabled.

## cPanel jailshell

Because cPanel's jailshell needs to mount filesystems (including bind mounts) after chrooting, both chroot_caps (due to needing CAP_SYS_ADMIN) and chroot_deny_mount will need to be disabled. To do this, either disable the respective options in your kernel configuration (CONFIG_GRKERNSEC_CHROOT_CAPS and CONFIG_GRKERNSEC_CHROOT_MOUNT) or disable them in an init script if GRKERNSEC_SYSCTL is enabled. Use the following commands:
We will be working with cPanel developers to see if the need for this workaround can be avoided in future jailshell versions.

## Firefox (or Iceweasel in Debian)

Mozilla Firefox and possibly all, if not some(?) of, the lib.so files in the folder (/usr/lib/firefox) with the Firefox binary (called /usr/lib/firefox/firefox) need mprotect disabled for flash to function. Without the Firefox binary having disabled mprotect Firefox will enter an infinite loop at startup or take minutes to load. Without the lib.so files having mprotect disabled any page encountered with Flash will surely run an infinite loop and the Firefox process will have to be killed.
The option must be disabled for just-in-time compilation of certain scripts for both xulrunner-stub and xulrunner-bin. See Grsecurity forums for more details.
The safest option would of course be denying mprotect and boycot sites that use just-in-time (JIT) flash scripts. You may disable JIT compilation in the browser by initiating the address about:config, search for "jit" in the page's integrated search bar, and double-click the options "javascript.options.methodjit.chrome" and "javascript.options.methodjit.content" to set them to "false".
Firefox >= 3.5 may need RANDMMAP to be disabled, if not it will enter in an infinite loop during startup. To disable, execute paxctl -r /firefox_binary. Usually the binary is somewhere in /usr/lib64/*firefox*. See http://bugs.gentoo.org/show_bug.cgi?id=278698 for more details. As of at least Firefox 13 on Ubuntu-based distros you can enable RANDMMAP.

## Google Chrome 15.0.874.106

On Google Chrome:
These PaX flags work well on my system with flash. Chrome's nacl does throw this however:

## Grub

Grub uses nested functions and thus needs either PAX_EMUTRAMP enabled in the kernel and EMUTRAMP enabled on affected binaries, or if PAX_EMUTRAMP is not enabled in the kernel, needs MPROTECT disabled on affected binaries. Depending on the version of grub in use, some of the following files may not exist, but you should mark all those that exist. To add EMUTRAMP, use the '-CE' argument to paxctl. To remove MPROTECT, use '-Cm'.

## GUFW/UFW firewalls or Update Manager

GUFW is an optional graphical application interface for the Ubuntu firewall (UFW), both of which use Python. Update Manager is a Gnome application for updating packages that also depends on Python. Really, any application that uses Python try enabling EMUTRAMP for the version of Python that is the dependency of your affected program (GUFW or Update Manager). (Example: # paxctl -E /usr/bin/Python2.7).

## IOQuake3

Ioquake3 requires disabling mprotect restrictions to run correctly.

## ISC DHCP Server

NOTE: grsecurity patches released as of May 4th, 2014 do not require the below modifications
On some systems, after upgrading to a grsecurity-enabled kernel with GRKERNSEC_PROC_USERGROUP enabled, the kernel log may be spammed with:
This may be due to unprivileged users not having access to /proc/net/dev as this dhcpd requires. You can confirm by running dhcpd -f from the command-line, which should display the following error:
To fix this, grep your kernel config for CONFIG_GRKERNSEC_PROC_GID, then add a group for that gid to /etc/group if it doesn't already exist. Then add dhcpd to that group. The added line will look similar to:
As the DHCP server is continually attempting to respawn, upon making this change you should find it running properly.

## Java

With problems with an epoll stack trace lookup . Also there is a problem with just-in-time compilation. Disable mprotect for /usr/lib/jvm/java-6-sun-1.6.0.10/jre/bin/java and /usr/lib/jvm/java-6-sun-1.6.0.10/jre/bin/javaws.

## Nagios

Nagios needs to be able to view all processes on the system in order to accurately portray service status and performance statistics. It must therefore be run with the group of the CONFIG_GRKERNSEC_PROC_GID you configured, or as set with the grsec_proc_gid kernel command-line option.

## Node.js

Node.js needs to execute arbitrary code at runtime. To permit this, mprotect needs to be disabled. On most systems, this can be accomplished with the command:
Note: For certain apps like electron, you will need to disable mprotect for both the electron and nodejs executables

## Openoffice.org

Openoffice.org uses two binaries which need custom settings to work. Both /usr/lib/openoffice/program/soffice.bin and /usr/lib/openoffice/program/unopkg.bin need to have unrestricted mprotect.

## libreoffice.org

the same as openoffice.org, but libreoffice.org need to have unrestricted mprotect for:
/usr/lib/jvm/java-6-openjdk-amd64/jre/bin/java to work if you use libreoffice-base: Database.

## PHP and other applications that set their own resource limits

While Apache/PHP run very well with a grsec/PaX enabled kernel, you could feel like there are possible memory leaks or strange OOM (out of memory) errors with PHP using a PaX enabled kernel with the SEGMEXEC flag enabled. There's no memory leak, and the OOM errors are normal, particularly if you didn't set high enough resource limits.
Concerning "abnormal" memory usage with PHP and SEGMEXEC flag enabled, see spender's answers on http://bugs.php.net/bug.php?id=49501 comments:

## X.org

X.org might need some specific kernel settings during configuration (depending on the hardware and the drivers used X won't run with non-executable pages (PAX_NOEXEC)). The problem manifested especially in XFree4. Although, recent versions of X.org are known to work with non-executable pages enabled. If you run into problems with X watch your non-executeble settings.
Some users experience mouse freezes when the system load is high. Typically the mouse pointer is reset, but stays in the upper left corner of the screen. This behaviour was found to occur with certain pre-emption settings . It seems to be an interaction between forced-preemption and KERNEXEC. You should be able to re-enable KERNEXEC as long as you disable preemption or use voluntary preemption.
According to the Pax-Team KERNEXEC should work as is, since the changes should be only basic functions like open/close functions. If you should experience problems switch to voluntary or none pre-emption.

# Reporting Bugs
## Contacts

Submitting bug reports to the proper developer will help get your bug resolved quicker. Though the developers of PaX and grsecurity will forward bug reports to each other, doing so may delay the resolution of your problem.
For bugs within grsecurity features, submit bug reports to: spender@grsecurity.net. For bugs within PaX, submit bug reports to pageexec@freemail.hu.
Bug reports can also be submitted to the gsecurity forums. (this is the preferred method). The developers monitor RSS feeds of the forums to be able to respond to bug reports quickly.
If possible, avoid submitting bug reports to the grsecurity mailing list, as it is mainly intended for announcements or other important topics.

## Requirements

To be able to reproduce the problem you're experiencing or properly debug it, information will be requested of you depending on the type of bug you are reporting. For any large files that are requested, such as the kernel's vmlinux file, please attempt to make these available via a website (you can use a free file uploading service) as they will likely be rejected by the developers' mail servers. Additional information may be requested for debugging purposes (particularly if the problem cannot be reproduced by the developers), but below is specified the minimum requested information.
For any bug you report, please specify the name of the patch you have applied to the kernel. Please also note that the developers only support the latest test patches, as a bug reported in an older patch may have already been fixed in the latest test patch.
A properly submitted bug report that includes the requested information below up-front greatly improves turnaround time for getting your problem solved.

### Compilation Errors

    A copy of your kernel .config

### Build/Linking Errors

    A copy of your kernel .config
    Your binutils version (ld --version)

### RBAC Problems

    A copy of your kernel .config
    A copy of your policy file
    A listing of the steps performed to produce the problem

### Kernel Crashes/Hangs

    A copy of your kernel .config
    Your binutils version (ld --version)
    A copy of your vmlinux file (from the kernel source tree)
    A copy of your bzImage file (from the /boot directory)
    A copy of your System.map file (from the /boot directory)
    The OOPS report, if one exists (take a photo of the screen if you are unable to capture it on disk). Note: we previously required that GRKERNSEC_HIDESYM be disabled for bug reports. This is no longer the case. Any recent grsecurity patch doesn't require GRKERNSEC_HIDESYM to be disabled for symbols to be displayed in OOPs messages.
    A description of the machine's hardware (particularly any non-standard hardware)
    Information about your Virtual Machine setup (if applicable): preferred execution mode and kernel paravirtualization
    Steps required to reproduce the crash (if not before init starts)

# Appendix
## Introduction

This is a list of all grsecurity and PaX configuration options in the kernel. You can access this same information using the kernel configuration's built-in help. This page contains only the configuration options present in the latest stable grsecurity release. The grsecurity options are available under Security options » Grsecurity.
Each option contains the corresponding kernel configuration symbol (e.g. GRKERNSEC_FIFO), all related sysctl variable names if the option is configurable through sysctl, and description of the option.

# Grsecurity (top level menu)
## Grsecurity

GRKERNSEC

## Configuration Method
### Automatic

GRKERNSEC_CONFIG_AUTO

### Custom

GRKERNSEC_CONFIG_CUSTOM

## Usage Type
### Server

CARTERPONDSEC_CONFIG_SERVER
Carterpoundssec

### Desktop

GRKERNSEC_CONFIG_DESKTOP

## Virtualization Type
### None

GRKERNSEC_CONFIG_VIRT_NONE

### Guest

GRKERNSEC_CONFIG_VIRT_GUEST

### Host

GRKERNSEC_CONFIG_VIRT_HOST

## Virtualization Hardware
### EPT/RVI Processor Support

GRKERNSEC_CONFIG_VIRT_EPT

### First-gen/No Hardware Virtualization

GRKERNSEC_CONFIG_VIRT_SOFT

## Virtualization Software
### Xen

GRKERNSEC_CONFIG_VIRT_XEN

### VMWare

GRKERNSEC_CONFIG_VIRT_VMWARE

### KVM

GRKERNSEC_CONFIG_VIRT_KVM

### VirtualBox

GRKERNSEC_CONFIG_VIRT_VIRTUALBOX

## Required Priorities
### Performance

GRKERNSEC_CONFIG_PRIORITY_PERF

### Security

GRKERNSEC_CONFIG_PRIORITY_SECURITY

## Default Special Groups
### GID exempted from /proc restrictions

GRKERNSEC_PROC_GID

### GID for TPE-untrusted users

GRKERNSEC_TPE_UNTRUSTED_GID

### GID for TPE-trusted users

GRKERNSEC_TPE_TRUSTED_GID

### GID for users with kernel-enforced SymlinksIfOwnerMatch

GRKERNSEC_SYMLINKOWN_GID

## Customize Configuration
### PaX
#### Enable various PaX features

PAX

#### PaX Control
##### Support soft mode

PAX_SOFTMODE

##### Use legacy ELF header marking

PAX_EI_PAX

##### Use ELF program header marking

PAX_PT_PAX_FLAGS

##### Use filesystem extended attributes marking

PAX_XATTR_PAX_FLAGS

##### MAC system integration
###### none

PAX_NO_ACL_FLAGS

###### direct

PAX_HAVE_ACL_FLAGS

###### hook

PAX_HOOK_ACL_FLAGS

#### Non-executable pages
##### Enforce non-executable pages

PAX_NOEXEC

##### Paging based non-executable pages

PAX_PAGEEXEC

##### Segmentation based non-executable pages

PAX_SEGMEXEC

##### Emulate trampolines

PAX_EMUTRAMP

##### Automatically emulate sigreturn trampolines

PAX_EMUSIGRT

##### Restrict mprotect

PAX_MPROTECT

##### Use legacy/compat protection demoting (read help)

PAX_MPROTECT_COMPAT

##### Allow ELF text relocations (read help)

PAX_ELFRELOCS

##### Allow ELF ET_EXEC text relocations

PAX_ETEXECRELOCS

##### Automatically emulate ELF PLT

PAX_EMUPLT

##### Emulate old glibc resolver stub

PAX_DLRESOLVE

##### Enforce non-executable kernel pages

PAX_KERNEXEC

##### Return Address Instrumentation Method
###### bts

PAX_KERNEXEC_PLUGIN_METHOD_BTS

##### bts

PAX_KERNEXEC_PLUGIN_METHOD

##### Minimum amount of memory reserved for module code

PAX_KERNEXEC_MODULE_TEXT

#### Address Space Layout Randomization
##### Address Space Layout Randomization

PAX_ASLR

##### Randomize kernel stack base

PAX_RANDKSTACK

##### Randomize user stack base

PAX_RANDUSTACK

##### Randomize mmap base

PAX_RANDMMAP

#### Miscellaneous hardening features
##### Sanitize all freed memory

PAX_MEMORY_SANITIZE

##### Sanitize kernel stack

PAX_MEMORY_STACKLEAK

##### Forcibly initialize local variables copied to userland

PAX_MEMORY_STRUCTLEAK

##### Prevent invalid userland pointer dereference

PAX_MEMORY_UDEREF

##### Prevent various kernel object reference counter overflows

PAX_REFCOUNT

##### Automatically constify eligible structures

PAX_CONSTIFY_PLUGIN

##### Harden heap object copies between kernel and userland

PAX_USERCOPY

##### Prevent various integer overflows in function size parameters

PAX_SIZE_OVERFLOW

##### Generate some entropy during boot and runtime

PAX_LATENT_ENTROPY

##### Prevent code reuse attacks

PAX_RAP

### Memory Protections
#### Deny reading/writing to /dev/kmem, /dev/mem, and /dev/port

GRKERNSEC_KMEM

#### Restrict VM86 mode

GRKERNSEC_VM86

#### Disable privileged I/O

GRKERNSEC_IO Related sysctl variables:
    kernel.grsecurity.disable_priv_io

#### Harden BPF JIT against spray attacks

GRKERNSEC_JIT_HARDEN

#### Disable unprivileged PERF_EVENTS usage by default

GRKERNSEC_PERF_HARDEN

#### Insert random gaps between thread stacks

GRKERNSEC_RAND_THREADSTACK

#### Harden ASLR against information leaks and entropy reduction

GRKERNSEC_PROC_MEMMAP

#### Prevent kernel stack overflows

GRKERNSEC_KSTACKOVERFLOW

#### Deter exploit bruteforcing

GRKERNSEC_BRUTE Related sysctl variables:
    kernel.grsecurity.deter_bruteforce

#### Harden module auto-loading

GRKERNSEC_MODHARDEN

#### Hide kernel symbols

GRKERNSEC_HIDESYM

#### Randomize layout of sensitive kernel structures

GRKERNSEC_RANDSTRUCT

#### Use cacheline-aware structure randomization

GRKERNSEC_RANDSTRUCT_PERFORMANCE

#### Active kernel exploit response

GRKERNSEC_KERN_LOCKOUT

#### Old ARM userland compatibility

GRKERNSEC_OLD_ARM_USERLAND

### Role Based Access Control Options
#### Disable RBAC system

GRKERNSEC_NO_RBAC

#### Hide kernel processes

GRKERNSEC_ACL_HIDEKERN

#### Maximum tries before password lockout

GRKERNSEC_ACL_MAXTRIES

#### Time to wait after max password tries, in seconds

GRKERNSEC_ACL_TIMEOUT

### Filesystem Protections
#### Proc restrictions

GRKERNSEC_PROC

#### Restrict /proc to user only

GRKERNSEC_PROC_USER

#### Allow special group

GRKERNSEC_PROC_USERGROUP

#### GID exempted from /proc restrictions

GRKERNSEC_PROC_GID

#### Additional restrictions

GRKERNSEC_PROC_ADD

#### Linking restrictions

GRKERNSEC_LINK Related sysctl variables:
    kernel.grsecurity.linking_restrictions

#### Kernel-enforced SymlinksIfOwnerMatch

GRKERNSEC_SYMLINKOWN Related sysctl variables:
    kernel.grsecurity.enforce_symlinksifowner
    kernel.grsecurity.symlinkown_gid

#### GID for users with kernel-enforced SymlinksIfOwnerMatch

GRKERNSEC_SYMLINKOWN_GID

#### FIFO restrictions

GRKERNSEC_FIFO Related sysctl variables:
    kernel.grsecurity.fifo_restrictions

#### Sysfs/debugfs restriction

GRKERNSEC_SYSFS_RESTRICT

#### Runtime read-only mount protection

GRKERNSEC_ROFS Related sysctl variables:
    kernel.grsecurity.romount_protect

#### Eliminate stat/notify-based device sidechannels

GRKERNSEC_DEVICE_SIDECHANNEL

#### Chroot jail restrictions

GRKERNSEC_CHROOT

#### Deny mounts

GRKERNSEC_CHROOT_MOUNT Related sysctl variables:
    kernel.grsecurity.chroot_deny_mount

#### Deny double-chroots

GRKERNSEC_CHROOT_DOUBLE Related sysctl variables:
    kernel.grsecurity.chroot_deny_chroot

#### Deny pivot_root in chroot

GRKERNSEC_CHROOT_PIVOT Related sysctl variables:
    kernel.grsecurity.chroot_deny_pivot

#### Enforce chdir("/")

GRKERNSEC_CHROOT_CHDIR Related sysctl variables:
    kernel.grsecurity.chroot_enforce_chdir

#### Deny (f)chmod +s

GRKERNSEC_CHROOT_CHMOD Related sysctl variables:
    kernel.grsecurity.chroot_deny_chmod

#### Deny fchdir out of chroot

GRKERNSEC_CHROOT_FCHDIR Related sysctl variables:
    kernel.grsecurity.chroot_deny_fchdir

#### Deny mknod

GRKERNSEC_CHROOT_MKNOD Related sysctl variables:
    kernel.grsecurity.chroot_deny_mknod

#### Deny shmat out of chroot

GRKERNSEC_CHROOT_SHMAT Related sysctl variables:
    kernel.grsecurity.chroot_deny_shmat

#### Deny access to abstract AF_UNIX sockets out of chroot

GRKERNSEC_CHROOT_UNIX Related sysctl variables:
    kernel.grsecurity.chroot_deny_unix

#### Protect outside processes

GRKERNSEC_CHROOT_FINDTASK Related sysctl variables:
    kernel.grsecurity.chroot_findtask

#### Restrict priority changes

GRKERNSEC_CHROOT_NICE Related sysctl variables:
    kernel.grsecurity.chroot_restrict_nice

#### Deny sysctl writes

GRKERNSEC_CHROOT_SYSCTL Related sysctl variables:
    kernel.grsecurity.chroot_deny_sysctl

#### Capability restrictions

GRKERNSEC_CHROOT_CAPS Related sysctl variables:
    kernel.grsecurity.chroot_caps

#### Exempt initrd tasks from restrictions

GRKERNSEC_CHROOT_INITRD

### Kernel Auditing
#### Single group for auditing

GRKERNSEC_AUDIT_GROUP Related sysctl variables:
    kernel.grsecurity.audit_gid
    kernel.grsecurity.audit_group

#### GID for auditing

GRKERNSEC_AUDIT_GID

#### Exec logging

GRKERNSEC_EXECLOG Related sysctl variables:
    kernel.grsecurity.exec_logging

#### Resource logging

GRKERNSEC_RESLOG Related sysctl variables:
    kernel.grsecurity.resource_logging

#### Log execs within chroot

GRKERNSEC_CHROOT_EXECLOG Related sysctl variables:
    kernel.grsecurity.chroot_execlog

#### Ptrace logging

GRKERNSEC_AUDIT_PTRACE Related sysctl variables:
    kernel.grsecurity.audit_ptrace

#### Chdir logging

GRKERNSEC_AUDIT_CHDIR Related sysctl variables:
    kernel.grsecurity.audit_chdir

#### (Un)Mount logging

GRKERNSEC_AUDIT_MOUNT Related sysctl variables:
    kernel.grsecurity.audit_mount

#### Signal logging

GRKERNSEC_SIGNAL Related sysctl variables:
    kernel.grsecurity.signal_logging

#### Fork failure logging

GRKERNSEC_FORKFAIL Related sysctl variables:
    kernel.grsecurity.forkfail_logging

#### Time change logging

GRKERNSEC_TIME Related sysctl variables:
    kernel.grsecurity.timechange_logging

#### /proc/<pid>/ipaddr support

GRKERNSEC_PROC_IPADDR

#### Denied RWX mmap/mprotect logging

GRKERNSEC_RWXMAP_LOG Related sysctl variables:
    kernel.grsecurity.rwxmap_logging

### Executable Protections
#### Dmesg(8) restriction

GRKERNSEC_DMESG Related sysctl variables:
    kernel.grsecurity.dmesg

#### Deter ptrace-based process snooping

GRKERNSEC_HARDEN_PTRACE Related sysctl variables:
    kernel.grsecurity.harden_ptrace

#### Require read access to ptrace sensitive binaries

GRKERNSEC_PTRACE_READEXEC Related sysctl variables:
    kernel.grsecurity.ptrace_readexec

#### Enforce consistent multithreaded privileges

GRKERNSEC_SETXID Related sysctl variables:
    kernel.grsecurity.consistent_setxid

#### Disallow access to overly-permissive IPC objects

GRKERNSEC_HARDEN_IPC Related sysctl variables:
    kernel.grsecurity.harden_ipc

#### Trusted Path Execution (TPE)

GRKERNSEC_TPE Related sysctl variables:
    kernel.grsecurity.tpe
    kernel.grsecurity.tpe_gid

#### Partially restrict all non-root users

GRKERNSEC_TPE_ALL Related sysctl variables:
    kernel.grsecurity.tpe_restrict_all

#### Invert GID option

GRKERNSEC_TPE_INVERT Related sysctl variables:
    kernel.grsecurity.tpe_invert

#### GID for TPE-untrusted users

GRKERNSEC_TPE_UNTRUSTED_GID

#### GID for TPE-trusted users

GRKERNSEC_TPE_TRUSTED_GID

### Network Protections
#### Larger entropy pools

GRKERNSEC_RANDNET

#### TCP/UDP blackhole and LAST_ACK DoS prevention

GRKERNSEC_BLACKHOLE Related sysctl variables:
    kernel.grsecurity.ip_blackhole
    kernel.grsecurity.lastack_retries

#### Disable TCP Simultaneous Connect

GRKERNSEC_NO_SIMULT_CONNECT

#### Socket restrictions

GRKERNSEC_SOCKET

#### Deny any sockets to group

GRKERNSEC_SOCKET_ALL Related sysctl variables:
    kernel.grsecurity.socket_all
    kernel.grsecurity.socket_all_gid

#### GID to deny all sockets for

GRKERNSEC_SOCKET_ALL_GID

#### Deny client sockets to group

GRKERNSEC_SOCKET_CLIENT Related sysctl variables:
    kernel.grsecurity.socket_client
    kernel.grsecurity.socket_client_gid

#### GID to deny client sockets for

GRKERNSEC_SOCKET_CLIENT_GID

#### Deny server sockets to group

GRKERNSEC_SOCKET_SERVER Related sysctl variables:
    kernel.grsecurity.socket_server
    kernel.grsecurity.socket_server_gid

#### GID to deny server sockets for

GRKERNSEC_SOCKET_SERVER_GID

### Physical Protections
#### Deny new USB connections after toggle

GRKERNSEC_DENYUSB Related sysctl variables:
    kernel.grsecurity.deny_new_usb

#### Reject all USB devices not connected at boot

GRKERNSEC_DENYUSB_FORCE

### Sysctl Support
#### Sysctl support

GRKERNSEC_SYSCTL

#### Extra sysctl support for distro makers (READ HELP)

GRKERNSEC_SYSCTL_DISTRO

#### Turn on features by default

GRKERNSEC_SYSCTL_ON

### Logging Options
#### Seconds in between log messages (minimum)

GRKERNSEC_FLOODTIME

#### Number of messages in a burst (maximum)

GRKERNSEC_FLOODBURST

## Appendix Tables

| Mode | Meaning |
| u | This role is a user role. That is, the role name must be an existing user on the system. |
| g | This role is a group role. That is, the role name must be an existing group on the system. |
| s | This role is a special role, meaning it does not belong to a user or group and does not require an enforced secure policy base to be included in the ruleset. |
| l | Lowercase L. This role has learning enabled. |
| A | This role is an administrative role, thus it has special privileges that normal roles do not have. In particular, this role bypasses the additional ptrace and library loading restrictions. |
| G | This role can use gradm to authenticate to the kernel. A policy for gradm will automatically be added to the role. |
| N | This role does not require authentication. To access this role, use 'gradm -n <rolename>'. |
| P | This role uses Pluggable Authentication Modules (PAM) for authentication. |
| T | This role has Trusted Path Execution (TPE) enabled. |
| R | The role is persistent. When the shell/session in which authorization was done is terminated, spawned processes won't be dropped to non-special role. Do NOT use this flag with any role that does anything but shut the system down. |

## role_transitions

Role transitions specify which special roles a given role is allowed to authenticate to. This applies to special roles that do not require password authentication as well. If a user tries to authenticate to a role that is not within his transition table, he will receive a permission denied error. A common mistake when creating a new special role is forgetting to create a role_transitions rule for the role that will transition to the special role, which a user confuses with having entered an incorrect password. The role_transitions rule is added below the declaration of a role, but before any subject declaration.
Usage:
Example:

## role_allow_ip

This rule restricts the use of a role to a list of IPs. If a user is on the system who would normally get the rule does not belong to the specified list of IPs, the system falls back through its method of determining a role for the user (checking for an applicable group role then falling back to the default role). This rule can be specified multiple times for a role. Like role_transitions, it should be added below the declaration of a role, but before any subject declaration.
Usage:
Example:
A netmask of 0.0.0.0/32 permits use of the role only by local processes that haven't been used by remote clients .

## role_umask

This rule can, depending on the mode specified, ensure a number of security properties on files under the control of a given user. One use case is to ensure that a user cannot accidentally or intentionally create a file that others can read (a confidentiality issue). Another is to ensure a user cannot accidentally or intentionally create a file that can be written by others (an integrity issue). Like previous role attributes, it should be added below the declaration of a role, but before any subject declaration.
Usage:
Example:
| Mode | Meaning |
| a | Allow this process to talk to the /dev/grsec device. |
| b | Enable process accounting for processes in this subject. |
| d | Protect the /proc/<pid>/fd, /proc/<pid>/mem, /proc/<pid>/cmdline, and /proc/<pid>/environ entries for processes in this subject, |
| h | This process is hidden and only viewable by processes with the v mode. |
| i | Enable inheritance-based learning, causing all accesses of this subject and anything it executes to be logged as originating from this subject. The policy generated from this learning will have the inheritance flag added to every file executed from this subject. |
| k | This process can kill protected processes. |
| l | Enables learning mode for this process. |
| o | Override ACL inheritance for this process. |
| p | This process is protected; it can only be killed by processes with the k mode, or by processes within the same subject. |
| r | Relax ptrace restrictions (allows ptracing of processes other than one's own children). |
| s | (In v2.2.1 and above): Enable AT_SECURE when entering this subject. This enables the same environment sanitization that occurs in glibc upon execution of a suid binary. |
| t | Allow ptracing of any process (do not use unless necessary, allows ptrace to cross subject boundaries). This flag also allows a process to use CLONE_FS and execute a binary that causes a subject change. |
| v | This process can view hidden processes. |
| x | Allows executable anonymous shared memory for this subject. |
| A | Protect the shared memory of this subject. No other processes but processes contained within this subject may access the shared memory of this subject. |
| C | Auto-kill all processes belonging to the attacker's IP address upon violation of security policy. |
| K | When processes belonging to this subject generate an alert, kill the process. |
| O | Allow loading of writable libraries. |
| T | Deny execution of binaries or scripts that are writable by any other subject in the policy. This flag is evaluated at policy enable time. All binaries with execute permission that are writable by another subject (ignoring special roles) will be reported and the RBAC system will not allow itself to be enabled until the changes are made. |

## user/group transitions

You may specify what users and groups a given subject can transition to. This can be done on an inclusive or exclusive basis. Omitting these rules allows a subject with proper privilege granted by capabilities to transition to any user/group.
Usage:
Example:

## ip_override

It is possible to force a given subject to bind to a particular IP address on the machine. This can be useful for some sandboxed environments, to ensure the source IP used from the sandbox is one determined by RBAC policy. To restrict what other source IP addresses a subject can bind to, use the normal IP ACL support of the RBAC system. This option is solely used to override an application's use of INADDR_ANY when connecting out or binding to a local port.
Usage:
Example:

## Socket policy (bind/connect/sock_allow_family)

bind/connect are described under The RBAC System.
When connect/bind rules are used, additional rules will be required to unlock the use of additional socket families (outside of the common unix family). Multiple families can be specified per line.
To enable use of IPv6, add the line:
To enable use of netlink, add the line:
To enable all other families, add the line:
Object Permission Modes :
| Mode | Meaning |
Object Auditing Flags :
| Mode | Meaning |
Other Object Flags :
| Mode | Meaning |
This table lists all PaX flags that can be forced on or off in the policy, regardless of the flags on the binary, by using + or - before the flag name.
| Flag | Description | Details |
| PAX_EMUTRAMP | PaX Trampoline emulation | http://pax.grsecurity.net/docs/emutramp.txt |
| PAX_MPROTECT | PaX MPROTECT | http://pax.grsecurity.net/docs/mprotect.txt |
| PAX_PAGEEXEC | PaX PAGEEXEC | http://pax.grsecurity.net/docs/pageexec.txt |
| PAX_RANDMMAP | PaX ASLR | http://pax.grsecurity.net/docs/randmmap.txt |
| PAX_SEGMEXEC | PaX SEGMEXEC | http://pax.grsecurity.net/docs/segmexec.txt |
This table lists all standard Linux capabilities and one special capability related to grsecurity. With capabilities, the system is divided into logical groups that may be individually granted to, or removed from, different processes. See [[../../The RBAC System#Capability Restrictions|Capability Restrictions]] for more information.
| Capability Name | Meaning |
| CAP_ALL | CAP_ALL is not a real capability, but was coded into gradm to represent all capabilities. Therefore to denote dropping of all capabilities, but CAP_SETUID, -CAP_ALL and +CAP_SETUID would be used. |
| CAP_CHOWN | In a system with the [_POSIX_CHOWN_RESTRICTED] option defined, this overrides the restriction of changing file ownership and group ownership. |
| CAP_DAC_OVERRIDE | Override all DAC access, including ACL execute access if [_POSIX_ACL] is defined. Excluding DAC access covered by CAP_LINUX_IMMUTABLE. |
| CAP_DAC_READ_SEARCH | Overrides all DAC restrictions, regarding read and search on files and directories, including ACL restrictions, if [_POSIX_ACL] is defined. Excluding DAC access covered by CAP_LINUX_IMMUTABLE. |
| CAP_FOWNER | Overrides all restrictions about allowed operations on files, where file owner ID must be equal to the user ID, except where CAP_FSETID is applicable. It doesn't override MAC and DAC restrictions. |
| CAP_FSETID | Overrides the following restrictions, that the effective user ID shall match the file owner ID, when setting the S_ISUID and S_ISGID bits on that file; that the effective group ID (or one of the supplementary group IDs) shall match the file owner ID when setting the S_ISGID bit on that file; that the S_ISUID and S_ISGID bits are cleared on successful return from chown(2) (not implemented). |
| CAP_KILL | Overrides the restriction, that the real or effective user ID of a process, sending a signal, must match the real or effective user ID of the process receiving the signal. |
| CAP_SETGID | Allows setgid(2) manipulation.Allows setgroups(2).Allows forged gids on socket credentials passing. |
| CAP_SETUID | Allows set*uid(2) manipulation (including fsuid).Allows forged pids on socket credentials passing. |
| CAP_SETPCAP | Without VFS support for capabilities:Transfer any capability in your permitted set to any pid, remove any capability in your permitted set from any pid. With VFS support for capabilities (neither of above, but)Add any capability from current's capability bounding set to the current process' inheritable setAllow taking bits out of capability bounding set.Allow modification of the securebits for a process. |
| CAP_LINUX_IMMUTABLE | Allow modification of S_IMMUTABLE and S_APPEND file attributes. |
| CAP_NET_BIND_SERVICE | Allows binding to TCP/UDP sockets below 1024.Allows binding to ATM VCIs below 32. |
| CAP_NET_BROADCAST | Allow broadcasting, listen to multicast. |
| CAP_NET_ADMIN | Allow interface configuration.Allow administration of IP firewall, masquerading and accounting.Allow setting debug option on sockets.Allow modification of routing tables.Allow setting arbitrary process / process group ownership on sockets.Allow binding to any address for transparent proxying.Allow setting TOS (type of service).Allow setting promiscuous mode.Allow clearing driver statistics.Allow multicasting.Allow read/write of device–specific registers.Allow activation of ATM control sockets. |
| CAP_NET_RAW | Allow use of RAW sockets.Allow use of PACKET sockets. |
| CAP_IPC_LOCK | Allow locking of shared memory segments.Allow mlock and mlockall (which doesn't really have anything to do with IPC). |
| CAP_IPC_OWNER | Override IPC ownership checks. |
| CAP_SYS_MODULE | Insert and remove kernel modules – modify kernel without limit. |
| CAP_SYS_RAWIO | Allow ioperm/iopl accessAllow sending USB messages to any device via /proc/bus/usb' |
| CAP_SYS_CHROOT | Allow use of chroot. |
| CAP_SYS_PTRACE | Allow ptrace of any process. |
| CAP_SYS_PACCT | Allow configuration of process accounting. |
| CAP_SYS_ADMIN | Allow configuration of the secure attention key.Allow administration of the random device.Allow examination and configuration of disk quotas.Allow configuring the kernel's syslog (printk behaviour).Allow setting the domainname.Allow setting the hostname.Allow calling bdflush.Allow mount and umount, setting up new smb connection.Allow some autofs root ioctls.Allow nfsservctl.Allow VM86_REQUEST_IRQ.Allow to read/write pci config on alpha.Allow irix_prctl on mips (setstacksize).Allow flushing all cache on m68k (sys_cacheflush).Allow removing semaphores. Used instead of CAP_CHOWN to "chown" IPC message queues, semaphores and shared memory.Allow locking/unlocking of shared memory segment.Allow turning swap on/off.Allow forged pids on socket credentials passing.Allow setting readahead and flushing buffers on block devices.Allow setting geometry in floppy driver.Allow turning DMA on/off in xd driver.Allow administration of md devices (mostly the above, but some extra ioctls).Allow tuning the ide driver.Allow access to the nvram device.Allow administration of apm_bios, serial and bttv (TV) device.Allow manufacturer commands in isdn CAPI support driver.Allow reading non–standardized portions of pci configuration space.Allow DDI debug ioctl on sbpcd driver.Allow setting up serial ports.Allow sending raw qic–117 commands.Allow enabling/disabling tagged queuing on SCSI controllers and sending arbitrary SCSI commands.Allow setting encryption key on loopback filesystem.Allow setting zone reclaim policy. |
| CAP_SYS_BOOT | Allow use of rebootAllow use of kexec syscall |
| CAP_SYS_NICE | Allow raising priority and setting priority on other (different UID) processes.Allow use of FIFO and round–robin (realtime) scheduling on own processes and setting the scheduling algorithm used by another process.Allow setting cpu affinity on other processes. |
| CAP_SYS_RESOURCE | Override resource limits. Set resource limits.Override quota limitsOverride reserved space on ext2 filesystemModify data journaling mode on ext3 filesystem (uses journaling resources). NOTE: ext2 honors fsuid when checking for resource overrides, so you can override using fsuid too.Override size restrictions on IPC message queues.Allow more than 64Hz interrupts from the real–time clock.Override max number of consoles on console allocation.Override max number of keymaps. |
| CAP_SYS_TIME | Allow manipulation of system clock.Allow irix_stime on mips.Allow setting the real–time clock. |
| CAP_SYS_TTY_CONFIG | Allow configuration of tty devices.Allow vhangup of tty. |
| CAP_MKNOD | Allow the privileged aspects of mknod. |
| CAP_LEASE | Allow taking of leases on files. |
| CAP_AUDIT_WRITE | Allow emitting auditing messages. |
| CAP_AUDIT_CONTROL | Allow administration of the kernel's auditing system. |
| CAP_SETFCAP | Allow the setting of file capabilities. |
| CAP_MAC_OVERRIDE | Override MAC access. The base kernel enforces no MAC policy. An LSM may enforce a MAC policy and if it does and it chooses to implement capability based overrides of that policy, this is the capability it should use to do so. |
| CAP_MAC_ADMIN | Allow MAC configuration or state changes. The base kernel requires no MAC configuration. An LSM may enforce a MAC policy, and if it does and it chooses to implement capability based checks on modifications to that policy or the data required to maintain it, this is the capability it should use to do so. |
| CAP_SYSLOG | Allow configuring the kernel's syslog (printk behaviour). |
| CAP_WAKE_ALARM | Allow triggering something that will wake the system. |
{{BookCat|filing=deep}}

## Introduction

This table lists all system resources that can be restricted by grsecurity. Grsecurity supports all the resources Linux supports, but uses slightly different names for them: The RLIMIT prefix has been replaced with RES. For example, the Linux resource RLIMIT_CPU is called RES_CPU in grsecurity.
For detailed information about resources in Linux, see the man page of getrlimit.

## Syntax and Examples

A single resource rule follows the following syntax:
An example of this syntax would be:
This would prevent the process from creating files that are bigger than 5 Kilobytes.
Using unlimited is valid for both the soft limit and the hard limit, to denote an unlimited resource. Note that by omitting a resource restriction, the system's default limits are used (as set by PAM or the application itself). If a resource is specified within the policy, the specific limits override the system's default limits for the given subject.
A number of suffixes are allowed when specifying resource limits. They are described below.
| Suffix | Meaning |
| s | Amount of time in seconds. |
| m | Amount of time in minutes. |
| h | Amount of time in hours. |
| d | Amount of time in days. |
| K | Size in kilobytes. |
| M | Size in megabytes. |
| G | Size in gigabytes. |
A full list of supported resources is supplied below.
| Resource Name | Meaning |
| RES_AS | The maximum size of the process's virtual memory (address space) in bytes. |
| RES_CORE | Maximum size of core file, in bytes. When 0 no core dump files are created. When non-zero, larger dumps are truncated to this size. |
| RES_CPU | CPU time limit in seconds. |
| RES_DATA | The maximum size of the process's data segment, in bytes (initialized data, uninitialized data, and heap). |
| RES_FSIZE | The maximum size of files, in bytes, that the process may create. |
| RES_LOCKS | A limit on the combined number of flock locks and fcntl leases that this process may establish. |
| RES_MEMLOCK | The maximum number of bytes of memory that may be locked into RAM. In effect this limit is rounded down to the nearest multiple of the system page size. |
| RES_MSGQUEUE | Specifies the limit on the number of bytes that can be allocated for POSIX message queues for the real user ID of the calling process |
| RES_NICE | Specifies a ceiling to which the process's nice value can be raised using setpriority(2) or nice(2). |
| RES_NOFILE | Specifies a value one greater than the maximum file descriptor number that can be opened by this process. |
| RES_NPROC | The maximum number of threads that can be created for the real user ID of the calling process. |
| RES_RSS | Specifies the limit (in pages) of the process's resident set (the number of virtual pages resident in RAM). This limit only has effect in Linux 2.4.x, x < 30. |
| RES_RTPRIO | Specifies a ceiling on the real-time priority that may be set for this process using sched_setscheduler(2) and sched_setparam(2). |
| RES_SIGPENDING | Specifies the limit on the number of signals that may be queued for the real user ID of the calling process. Both standard and real-time signals are counted for the purpose of checking this limit. |
| RES_STACK | The maximum size of the process stack, in bytes. |
| RES_RTTIME | Specifies a limit on the amount of CPU time that a process scheduled under a real-time scheduling policy may consume without making a blocking system call. for the purpose of this limit, each time a process makes a blocking system call, the count of its consumed CPU time is reset to zero. The CPU time count is not reset if the process continues trying to use the CPU but is preempted, if its time slice expires, or if it calls sched_yield(2). Upon reaching the soft limit, the process is sent a SIGXCPU signal. If the process catches or ignores this signal and continues consuming CPU time, then SIGXCPU will be generated once each second until the hard limit is reached, at which point the process is sent a SIGKILL signal. The intended use of this limit is to stop a runaway real-time process from locking up the system. |
| RES_CRASH | This is a pseudo-resource interpreted only by the RBAC system. The meaning of soft and hard limits are overridden for this resource. The intent of the resource is to be able to rate-limit bruteforced exploit attempts for a given subject. The soft limit for this resource is the number of times the subject is allowed to crash in ways that suggest an exploitation attempt. The hard limit specifies the amount of time those crashes are allowed to occur in. With a rule like RES_CRASH 3 30m one can limit a privileged binary to three exploit attempts every 10 minutes, deterring bruteforcing attempts. The RBAC system actively responds to bruteforcing attempts that overstep this limit. If the target is a setuid binary, the attacker has all of his/her processes killed and will be unable to log in for the remainder of the configured time. If the target is a forking network daemon, that daemon will be unable to fork additional copies of itself for the remainder of the configured time. |
Below is a table of every available option in grsecurity that can be changed at runtime. The options can be changed using the sysctl interface, or by echoing values to files in /proc/sys/kernel/grsecurity/. Available options vary depending on how grsecurity was configured. See Configuring and Installing grsecurity and Runtime configuration for more information.
To find out what options are available in your system, list the contents of /proc/sys/kernel/grsecurity. If you use the sysctl interface, all of grsecurity's option are prefixed with kernel.grsecurity (e.g. kernel.grsecurity.audit_chdir).
Clicking an option will take you to or at least close to its description in another appendix page.
All sysctl variables :
| Auditing | Chroot restrictions | Network-based features | Misc. options |

# Introduction

On this page you will find documentation regarding permissions to use material written by others before this Wikibook was started.

## The Original grsecurity Documentation

The original documentation for grsecurity was written by Brad Spengler, the author of grsecurity. This includes the ACL documentation and the grsecurity Quick-Start Guide (PDF).

## Permission to Use the Official Documentation

Below is the correspondence between myself (Meev0 (talk)) and Brad Spengler regarding the use of his works in this Wikibook.
   Sent at: Mon Apr 20, 2009 5:56 pm
   You may publish my answer to the original request (and this request too). You may copy/republish any and all parts of the grsecurity documentation. I don't think I put an explicit license on the documentation, but I consider it to be essentially public domain.
   -Brad
   Sent at: Mon Apr 20, 2009 5:27 pm Thanks!
   I'm making a separate page for the book that will include credits, links to the original documents and a copy of your message where you grant this permission.
   Just so that there is no misunderstanding 1) May I publish your answer to my original request? 2) In my request I mentioned wanting to copy "parts" which is very vague. Basically what's needed (IMO) is you clearly stating what parts of the grsecurity documentation can be published under the GNU Free Documentation License. I'm not a copyright lawyer, but I think the clearer the situation the better.
   I'll try to limit the amount of text I need to copy, as I like writing documentation, but most of technical notes are better left as they are.
   - Ville
   Sent at: Sat Apr 18, 2009 7:59 pm Of course, that's fine with me. Thanks again for your work, and hope things get better for you personally.
   -Brad
   Sent at: Sat Apr 18, 2009 5:41 pm Hi Brad,
   I wanted to ask about using the Grsecurity QuickStart guides (the quickstart.pdf and the newGradmDoc.pdf) in the Wikibook. As you are the copyright holder of both documents, I need your permission to copy parts from those files. Mainly I would like to copy the ACL documentation, as it would be silly for me to start writing it from scratch. Naturally I would credit you and include a link to the original documents.
   Below is a link to the copyright policy of Wikibooks. http://en.wikibooks.org/wiki/Wikibooks:Copyrights
   You can reach me by replying to this PM or by email at ***.
   - Ville

# External Links

* Official grsecurity website
* Official website of the PaX project