| .TH dpkg\-buildflags 1 "2011-09-13" "Debian Project" "dpkg suite" |
| .SH NAME |
| dpkg\-buildflags \- returns build flags to use during package build |
| . |
| .SH SYNOPSIS |
| .B dpkg\-buildflags |
| .RI [ option "...] [" command ] |
| . |
| .SH DESCRIPTION |
| \fBdpkg\-buildflags\fP is a tool to retrieve compilation flags to use during |
| build of Debian packages. |
| . |
| The default flags are defined by the vendor but they can be |
| extended/overriden in several ways: |
| .IP 1. |
| system-wide with \fB/etc/dpkg/buildflags.conf\fP; |
| .IP 2. |
| for the current user with \fB$XDG_CONFIG_HOME/dpkg/buildflags.conf\fP |
| where \fB$XDG_CONFIG_HOME\fP defaults to \fB$HOME/.config\fP; |
| .IP 3. |
| temporarily by the user with environment variables (see section |
| \fBENVIRONMENT\fP); |
| .IP 4. |
| dynamically by the package maintainer with environment variables set via |
| \fBdebian/rules\fP (see section \fBENVIRONMENT\fP). |
| .P |
| The configuration files can contain two types of directives: |
| .TP |
| .BI SET " flag value" |
| Override the flag named \fIflag\fP to have the value \fIvalue\fP. |
| .TP |
| .BI STRIP " flag value" |
| Strip from the flag named \fIflag\fP all the build flags listed in \fIvalue\fP. |
| .TP |
| .BI APPEND " flag value" |
| Extend the flag named \fIflag\fP by appending the options given in \fIvalue\fP. |
| A space is prepended to the appended value if the flag's current value is non-empty. |
| .TP |
| .BI PREPEND " flag value" |
| Extend the flag named \fIflag\fP by prepending the options given in \fIvalue\fP. |
| A space is appended to the prepended value if the flag's current value is non-empty. |
| .P |
| The configuration files can contain comments on lines starting with a hash |
| (#). Empty lines are also ignored. |
| .SH COMMANDS |
| .TP |
| .BI \-\-dump |
| Print to standard output all compilation flags and their values. It prints |
| one flag per line separated from its value by an equal sign |
| ("\fIflag\fP=\fIvalue\fP"). This is the default action. |
| .TP |
| .BI \-\-list |
| Print the list of flags supported by the current vendor |
| (one per line). See the \fBSUPPORTED FLAGS\fP section for more |
| information about them. |
| .TP |
| .BI \-\-export= format |
| Print to standard output shell (if \fIformat\fP is \fBsh\fP) or make |
| (if \fIformat\fP is \fBmake\fP) commands that can be used to export |
| all the compilation flags in the environment. If \fIformat\fP is |
| \fBconfigure\fP then the output can be used on a \fB./configure\fP |
| command-line. If the \fIformat\fP value is not |
| given, \fBsh\fP is assumed. Only compilation flags starting with an |
| upper case character are included, others are assumed to not be suitable |
| for the environment. |
| .TP |
| .BI \-\-get " flag" |
| Print the value of the flag on standard output. Exits with 0 |
| if the flag is known otherwise exits with 1. |
| .TP |
| .BI \-\-origin " flag" |
| Print the origin of the value that is returned by \fB\-\-get\fP. Exits |
| with 0 if the flag is known otherwise exits with 1. The origin can be one |
| of the following values: |
| .RS |
| .TP |
| .B vendor |
| the original flag set by the vendor is returned; |
| .TP |
| .B system |
| the flag is set/modified by a system-wide configuration; |
| .TP |
| .B user |
| the flag is set/modified by a user-specific configuration; |
| .TP |
| .B env |
| the flag is set/modified by an environment-specific configuration. |
| .RE |
| .TP |
| .B \-\-help |
| Show the usage message and exit. |
| .TP |
| .B \-\-version |
| Show the version and exit. |
| . |
| .SH SUPPORTED FLAGS |
| .TP |
| .B CFLAGS |
| Options for the C compiler. The default value set by the vendor |
| includes \fI\-g\fP and the default optimization level (\fI\-O2\fP usually, |
| or \fI\-O0\fP if the \fBDEB_BUILD_OPTIONS\fP environment variable defines |
| \fInoopt\fP). |
| .TP |
| .B CPPFLAGS |
| Options for the C preprocessor. Default value: empty. |
| .TP |
| .B CXXFLAGS |
| Options for the C++ compiler. Same as \fBCFLAGS\fP. |
| .TP |
| .B FFLAGS |
| Options for the Fortran compiler. Same as \fBCFLAGS\fP. |
| .TP |
| .B LDFLAGS |
| Options passed to the compiler when linking executables or shared |
| objects (if the linker is called directly, then |
| .B \-Wl |
| and |
| .B , |
| have to be stripped from these options). Default value: empty. |
| . |
| .SH FILES |
| .TP |
| .B /etc/dpkg/buildflags.conf |
| System wide configuration file. |
| .TP |
| .BR $XDG_CONFIG_HOME/dpkg/buildflags.conf " or " $HOME/.config/dpkg/buildflags.conf |
| User configuration file. |
| .SH ENVIRONMENT |
| There are 2 sets of environment variables doing the same operations, the |
| first one (DEB_\fIflag\fP_\fIop\fP) should never be used within |
| \fBdebian/rules\fP. It's meant for any user that wants to rebuild the |
| source package with different build flags. The second set |
| (DEB_\fIflag\fP_MAINT_\fIop\fP) should only be used in \fBdebian/rules\fP |
| by package maintainers to change the resulting build flags. |
| .TP |
| .BI DEB_ flag _SET |
| .TQ |
| .BI DEB_ flag _MAINT_SET |
| This variable can be used to force the value returned for the given |
| \fIflag\fP. |
| .TP |
| .BI DEB_ flag _STRIP |
| .TQ |
| .BI DEB_ flag _MAINT_STRIP |
| This variable can be used to provide a space separated list of options |
| that will be stripped from the set of flags returned for the given |
| \fIflag\fP. |
| .TP |
| .BI DEB_ flag _APPEND |
| .TQ |
| .BI DEB_ flag _MAINT_APPEND |
| This variable can be used to append supplementary options to the value |
| returned for the given \fIflag\fP. |
| .TP |
| .BI DEB_ flag _PREPEND |
| .TQ |
| .BI DEB_ flag _MAINT_PREPEND |
| This variable can be used to prepend supplementary options to the value |
| returned for the given \fIflag\fP. |
| .TP |
| .B DEB_BUILD_MAINT_OPTIONS |
| This variable can be used to disable/enable various hardening build |
| flags through the \fBhardening\fP option. See the \fBHARDENING\fP section |
| for details. |
| . |
| .SH HARDENING |
| Several compile-time options (detailed below) can be used to help harden |
| a resulting binary against memory corruption attacks, or provide |
| additional warning messages during compilation. Except as noted below, |
| these are enabled by default for architectures that support them. |
| .P |
| Each hardening feature can be enabled and disabled in the |
| \fBDEB_BUILD_MAINT_OPTIONS\fP environment variable's \fBhardening\fP |
| value with the "+" and "\-" modifier. For example, to enable the |
| "pie" feature and disable the "fortify" feature you can do this |
| in \fBdebian/rules\fP: |
| .P |
| export DEB_BUILD_MAINT_OPTIONS=hardening=+pie,\-fortify |
| .P |
| The special feature \fBall\fP can be used to enable or disable all |
| hardening features at the same time. Thus disabling everything and |
| enabling only "format" and "fortify" can be achieved with: |
| .P |
| export DEB_BUILD_MAINT_OPTIONS=hardening=\-all,+format,+fortify |
| . |
| .TP |
| .B format |
| This setting (enabled by default) adds |
| .B \-Wformat \-Wformat\-security \-Werror=format\-security |
| to \fBCFLAGS\fP and \fBCXXFLAGS\fP. This will warn about improper format |
| string uses, and will fail when format functions are used in a way that |
| that represent possible security problems. At present, this warns about |
| calls to \fBprintf\fP and \fBscanf\fP functions where the format string is |
| not a string literal and there are no format arguments, as in |
| \fBprintf(foo);\fP instead of \fPprintf("%s", foo);\fP |
| This may be a security hole if the format string came from untrusted |
| input and contains "%n". |
| . |
| .TP |
| .B fortify |
| This setting (enabled by default) adds |
| .B \-D_FORTIFY_SOURCE=2 |
| to \fBCFLAGS\fP and \fBCXXFLAGS\fP. During code generation the compiler |
| knows a great deal of information about buffer sizes (where possible), and |
| attempts to replace insecure unlimited length buffer function calls with |
| length-limited ones. This is especially useful for old, crufty code. |
| Additionally, format strings in writable memory that contain '%n' are |
| blocked. If an application depends on such a format string, it will need |
| to be worked around. |
| |
| Note that for this option to have any effect, the source must also |
| be compiled with \fB\-O1\fP or higher. |
| .TP |
| .B stackprotector |
| This setting (enabled by default) adds |
| .B \-fstack-protector \-\-param=ssp\-buffer\-size=4 |
| to \fBCFLAGS\fP and \fBCXXFLAGS\fP. This adds safety checks against stack |
| overwrites. This renders many potential code injection attacks into |
| aborting situations. In the best case this turns code injection |
| vulnerabilities into denial of service or into non-issues (depending on |
| the application). |
| |
| This feature requires linking against glibc (or another provider of |
| \fB__stack_chk_fail\fP), so needs to be disabled when building with |
| \fB\-nostdlib\fP or \fB\-ffreestanding\fP or similar. |
| . |
| .TP |
| .B relro |
| This setting (enabled by default) adds |
| .B \-Wl,\-z,relro |
| to \fBLDFLAGS\fP. During program load, several ELF memory sections need |
| to be written to by the linker. This flags the loader to turn these |
| sections read-only before turning over control to the program. Most |
| notably this prevents GOT overwrite attacks. |
| . |
| .TP |
| .B bindnow |
| This setting (disabled by default) adds |
| .B \-Wl,\-z,now |
| to \fBLDFLAGS\fP. During program load, all dynamic symbols are resolved, |
| allowing for the entire PLT to be marked read-only (due to \fBrelro\fP |
| above). |
| . |
| .TP |
| .B pie |
| This setting (disabled by default) adds \fB\-fPIE\fP to \fBCFLAGS\fP and |
| \fBCXXFLAGS\fP, and \fB\-fPIE \-pie\fP to \fBLDFLAGS\fP. Position Independent |
| Executable are needed to take advantage of Address Space Layout |
| Randomization, supported by some kernel versions. While ASLR can already |
| be enforced for data areas in the stack and heap (brk and mmap), the code |
| areas must be compiled as position-independent. Shared libraries already |
| do this (\-fPIC), so they gain ASLR automatically, but binary .text |
| regions need to be build PIE to gain ASLR. When this happens, ROP (Return |
| Oriented Programming) attacks are much harder since there are no static |
| locations to bounce off of during a memory corruption attack. |
| |
| This is not compatible with \fB\-fPIC\fP so care must be taken when |
| building shared objects. |
| |
| Additionally, since PIE is implemented via a general register, some |
| architectures (most notably i386) can see performance losses of up to |
| 15% in very text-segment-heavy application workloads; most workloads |
| see less than 1%. Architectures with more general registers (e.g. amd64) |
| do not see as high a worst-case penalty. |
| . |
| .SH AUTHOR |
| Copyright \(co 2010-2011 Rapha\[:e]l Hertzog |
| .sp |
| Copyright \(co 2011 Kees Cook |
| .sp |
| This is free software; see the GNU General Public Licence version 2 or |
| later for copying conditions. There is NO WARRANTY. |
| |