Grsecurity/How to Contribute

The easiest way to contribute is to enhance existing content by correcting misspelled words, or restructuring sentences or paragraphs to make them more readable. You are also very welcome to add new content by expanding pages that are under development, or by adding completely new pages if your text doesn't fit any of the other pages. As grsecurity is being actively developed and features are added and removed, help with keeping the content up to date is much appreciated.

On this page you will find background on why a particular structure was chosen for the book, who this book is for, and what style and formatting should be used. They are provided to help you write.

Book Structure

The book's structure follows the original documentation of the grsecurity project that had three main chapters: Installation, Configuration and Specification, and Using gradm and the Learning Mode. Configuration and Specification was retitled as Policy Configuration. Using gradm and the Learning Mode was retitled as Administration and was also moved before the Policy Configuration, because you must know how to manage grsecurity before you configure the policy. This is how we ended up with the core structure: Installation, Administration, Policy Configuration.

Target Audience

The book is meant for people who are capable of solving hardware and software problems of varying complexity on their own and who actually read the manual. They know their way around their favorite Linux distribution and are familiar with configuring and building software from source.

Objectives

The purpose of this book is to provide comprehensive, reliable, and up-to-date documentation of grsecurity and related tools. In addition to teaching how to do something, the book provides information about best practices and common pitfalls learned in practice. This is the main objective.

Each chapter has additional objectives that define what the reader must understand and know after they've read it. These objectives were defined after most of the book's core content was in place, so at the time of writing some chapters might not fulfill all of their objectives.

Introduction: The reader must understand on a basic level what grsecurity is, what are its goals and how those goals are realized. If he does not belong to our target audience he should still get a rough idea what grsecurity is about.

Installation: The reader must know:

• Where to get grsecurity, its administration tool gradm and the Linux kernel source.
• How to verify the authenticity of each package.
• How to apply the grsecurity patch properly.
• How to configure grsecurity's kernel configuration options (this includes PaX settings) and what he needs to consider before doing so.
• How to build and install a grsecurity-enabled kernel using his chosen distribution's tools.

Administration: The reader must know:

• How to install gradm, the administration tool.
• How to use gradm and especially the learning mode.
• How to configure grsecurity's features at runtime.
• What other useful tools are available, where to get them, and how to install and use them.
• How to troubleshoot application incompatibilities and problems with grsecurity.

Policy Configuration: The reader must know:

• What an RBAC system is and what is not, what it can provide when properly configured.
• What makes a secure policy.
• The policy structure and rules; he must be familiar with every configuration element and their parameters and configuration inheritance.

Reporting Bugs: The reader must know how to report bugs; what information is required, how to gather it, and where to send the reports.

Style and Conventions

• Headers should be title cased.
• Use the <pre> tag to display long commands, example program output, and file contents.
• Use the XWarning template when you need to point out an important security consideration or a possibly dangerous operation. It is easier to spot than the classic Warning template when scrolling.
• Use the Info template when you need to point out something that's related to the surrounding text.
• The name grsecurity should be written in lowercase and without special formatting unless it begins a sentence. This is how it is written on the grsecurity website.

Formatting

Note: This is still work in progress, and will change in the future. It will be finalized soon.

Italic

Used for file and directory names.

Boldface

Used for occasional emphasis, such as when introducing a new term.

Constant Width

Used in text for program and command names. Blocks of pre-formatted text is used in examples show what commands to execute and what their output should be.