aerc-patch

package: aerc

title: aerc-patch(7)

text:
# aerc-patch(7)

## NAME
aerc-patch - local patch management for aerc(1)

## SYNOPSIS
aerc provides support for managing local patch sets. In an email-based software development workflow, there are usually many different locally applied patch series for testing and reviewing. Managing the local repository can thus be challenging. With the local patch management system, aerc facilitates this bookkeeping process.

When applying a patch set, aerc creates a tag for those commits. With this tag, the patch set can be tracked and later dropped if needed. Patches are stored in a project data structure which also keeps track of the directory where the repository is. Multiple code bases can be tracked by defining a separate project for each.

## COMMANDS
The following :patch sub-commands are supported:

:patch init [-f] [<project>]

Creates a new project <project>. If <project> is not defined, aerc will use the last element of the current directory path. It also performs a search for a supported repository in the current directory. -f: Overwrite an existing project.

:patch list [-a]

:patch ls [-a]

Lists the current project with the tracked patch sets. -a: Lists all projects.

:patch apply [-c <cmd>] [-w <commit-ish>] <tag>

Applies the selected message(s) to the repository of the current project. It uses the :pipe command for this and keeps track of the applied patch. Completions for the <tag> are available based on the subject lines of the selected or marked messages.

-c <cmd>: Apply patches with the provided <cmd>. Any occurrence of '%r' in the command string will be replaced with the root directory of the current project. Note that this approach is not recommended in general and should only be used for very specific purposes, i.e. when a maintainer is applying a patch set via a separate script to deal with git trailers.

aerc will propose completions for the <tag> based on the subject lines of the selected or marked messages.

Example:

```
:patch apply -c "git -C %r am -3" fix_v2
```

-w <commit-ish>: Create a linked worktree for the current project at <commit-ish> and apply the patches to the linked worktree. A new project is created to store the worktree information. When this project is deleted, the worktree will be deleted as well.

Example:

```
:patch apply -w origin/master fix_v2
```

:patch drop <tag>

Drops the patch <tag> from the repository.

:patch rebase [<commit-ish>]

Rebases the patch data on commit <commit-ish>. If the <commit-ish> is omitted, aerc will use the base commit of the current project for the rebase.

:patch find [-f] <commit-hash>

Searches the messages in the current folder of the current account for the message associated with this commit hash based on the subject line. If a Message-ID is linked to a commit (i.e. when :patch apply was used) then find will first perform a search for the Message-ID.

-f: Filter the message list instead of just showing the search results. Only effective when search for Message-ID was not successful.

:patch cd

Changes the working directory to the root directory of the current project.

:patch term [<cmd>]

Opens a shell (or runs <cmd>) in the working directory of the current project.

:patch switch <project>

Switches the context to <project>.

:patch unlink [<project>]

Deletes all patch tracking data for <project> and unlinks it from a repository. If no project is provided, the current project is deleted.

:patch

Root command for path management. Use it to run the sub-commands.

## GETTING STARTED
Make sure you have an initialized project (see :patch init).

Now, there are two ways to get patches under the local patch management system:

•

Apply patches with the :patch apply command. This will automatically create a new tag for the applied commits.

•

Use :patch rebase. If there are some existing local patches in the commit history that should be managed by aerc, you can run :patch rebase <commit-ish> and set the <commit-ish> to the commit before the first patch that you want to include. For a git repository which has an upstream called origin, you would run :patch rebase origin/master.

## EXAMPLE
The following example demonstrates how to manage the local patch sets.

First, a project needs to be initialized. This is done by changing into the working directory where the project's repository is located. For this example, let's assume we have a project called bar in the directory /home/user/foo/bar.

```
:cd /home/user/foo/bar
```

and then creating a new project with

```
:patch init
```

If no name is provided to :patch init, aerc will use the last element of the working directory path (here: bar).

Now the patch tracking is ready for action. Go to the message list, mark a patch series and apply it:

```
:patch apply fix_v2
```

This will apply the selected patch set and assigns the fix_v2 tag to those commits. The tag helps to keep the commits grouped together, and will be helpful when we want to drop this exact patch set at a later point.

With :patch list you can verify that the patch set was correctly applied.

If there is a change in the underlying repository (e.g. by rebasing to upstream), the hashes of the applied local commits can change. :patch list can detect such a change and will then propose to rebase the internal data. To do this, run

```
:patch rebase
```

This will open an editor where you can adjust the correct tags again. You could also change the rebase point by providing an optional argument (e.g. a commit hash, or even HEAD~3 or origin/master, etc.).

To drop a patch set, use the tag that was assigned during applying:

```
:patch drop fix_v2
```

And to delete the project data in aerc:

```
:patch unlink bar
```

## SUPPORTED REVISION CONTROL SYSTEMS
The supported revision control systems are currently: git.

## SEE ALSO
aerc(1)

## AUTHORS
Originally created by Drew DeVault and maintained by Robin Jarry who is assisted by other open source contributors. For more information about aerc development, see https://sr.ht/~rjarry/aerc/.

branch: sisyphus


aerc-stylesets

title: aerc-stylesets(7)

text:
# aerc-stylesets(7)

## NAME
aerc-stylesets - styleset file specification for aerc(1)

## SYNOPSIS
aerc uses a simple configuration syntax to configure the styleset for its ui.

## STYLESET CONFIGURATION
The styleset is described as <object>.<attribute> = <value> pairs.

For example, in the line below, the foreground color of the style object msglist_unread is set to cornflowerblue

msglist_unread.fg = cornflowerblue

The configuration also allows wildcard matching of the keys to configure multiple style objects at a time.

## ATTRIBUTES
The following options are available to be modified for each of the style objects.

<object>.fg = <color>

The foreground color of the style object is set.

<object>.bg = <color>

The background color of the style object is set.

<object>.bold = true|false|toggle

The bold attribute of the style object is set/unset.

<object>.blink = true|false|toggle

The blink attribute of the style object is set/unset. The terminal needs to support blinking text.

<object>.underline = true|false|toggle

The underline attribute of the style object is set/unset. The terminal needs to support underline text.

<object>.italic = true|false|toggle

The italic attribute of the style object is set/unset. The terminal needs to support italic text.

<object>.dim = true|false|toggle

The dim attribute of the style object is set/unset. The terminal needs to support half-bright text.

<object>.reverse = true|false|toggle

Reverses the color of the style object. Exchanges the foreground and background colors. If the value is false, it doesn't change anything.

<object>.normal = true

All the attributes of the style object are unset. The value doesn't matter.

<object>.default = true

Set the style object to the default style of the context. Usually based on the terminal. The value doesn't matter.

## STYLE OBJECTS
The style objects represent the various ui elements or ui instances for styling.

Style Object

Description

default

The default style object used for normal ui elements while not using specialized configuration.

error

The style used to show errors.

warning

The style used when showing warnings.

success

The style used for success messages.

title

The style object used to style titles in ui elements.

header

The style object used to style headers in ui elements.

statusline_default

The default style applied to the statusline.

statusline_error

The style used for error messages in statusline.

statusline_success

The style used for success messages in statusline.

msglist_default

The default style for messages in a message list.

msglist_unread

Unread messages in a message list.

msglist_read

Read messages in a message list.

msglist_flagged

The messages with the flagged flag.

msglist_deleted

The messages marked as deleted.

msglist_marked

The messages with the marked flag.

msglist_result

The messages which match the current search.

msglist_answered

The messages marked as answered.

msglist_forwarded

The messages marked as forwarded.

msglist_gutter

The message list gutter.

msglist_pill

The message list scrollbar.

msglist_thread_folded

Visible messages that have folded thread children.

msglist_thread_context

The messages not matching the mailbox / query, displayed for context.

msglist_thread_orphan

Threaded messages that have a missing parent message.

dirlist_default

The default style for directories in the directory list.

dirlist_unread

The style used for directories with unread messages

dirlist_recent

The style used for directories with recent messages

part_switcher

Background for the part switcher in the message viewer.

part_filename

Attachment file name in the part switcher.

part_mimetype

Attachment/part MIME type in the part switcher.

completion_default

The default style for the completion engine.

completion_description

Completion item descriptions.

completion_gutter

The completion gutter.

completion_pill

The completion pill.

tab

The style for the tab bar.

stack

The style for ui stack element.

spinner

The style for the loading spinner.

border

The style used to draw borders (only the bg color is used unless you customize border-char-vertical and/or border-char-horizontal in aerc.conf).

selector_default

The default style for the selector ui element.

selector_focused

The focused item in a selector ui element.

selector_chooser

The item chooser in a selector ui element.

These next style objects only affect the built-in colorize filter and must be declared under a [viewer] section of the styleset file.

Style Object

Description

url

URLs.

header

RFC-822-like header names.

signature

Email signatures.

diff_meta

Patch diff meta lines.

diff_chunk

Patch diff chunks.

diff_chunk_func

Patch diff chunk function names.

diff_add

Patch diff added lines.

diff_del

Patch diff deleted lines.

quote_1

First level quoted text.

quote_2

Second level quoted text.

quote_3

Third level quoted text.

quote_4

Fourth level quoted text.

quote_x

Above fourth level quoted text.

User defined styles can be used to style arbitrary strings in go-templates (see .Style in aerc-templates(7)). User styles must be defined in the [user] ini section. Styles can be referenced by their name (e.g. red.fg is named "red").

Example:

```
[user]
red.fg=red
```

User styles are layered with other styles applied to the context in which they are rendered. The user style colors (fg and/or bg) will only be effective if the context style does not define any. Other boolean attributes will be merged with the underlying style boolean attributes.

For example, if the context style is:

fg=red bold

And the inline style is:

fg=yellow italic underline

The effective style will be:

fg=red bold italic underline

## FNMATCH STYLE WILDCARD MATCHING
The styleset configuration can be made simpler by using the fnmatch style wildcard matching for the style object.

The special characters used in the fnmatch wildcards are:

Pattern

Meaning

*

Matches everything

?

Matches any single character

For example, the following wildcards can be made using this syntax.

Example

Description

*.fg = blue

Set the foreground color of all style objects to blue.

*list.bg = hotpink

Set the background color of all style objects that end in list to hotpink.

Note that the statements in a given styleset are parsed in the order in which they are written. That means that with the following styleset:

```
msglist_marked.fg = pink
msglist_*.fg = white
```

The msglist_marked.fg attribute will be set to white.

## SELECTED MODIFIER
The selected modifier can be applied to any style object. The style provided for the selected modifier is applied on top of the style object it corresponds to.

If you would like to make sure message that are flagged as read in the msglist appear in yellow foreground and black background. You can specify that with this:

msglist_default.selected.fg = yellow msglist_default.selected.bg = black

If we specify the global style selected modifier using fnmatch as below:

*.selected.reverse = toggle

This toggles the reverse switch for selected version of all the style objects.

selected objects inherit from all attributes of their non-selected counterparts. selected statements are parsed after non-selected ones and effectively override the attributes of the non-selected style object.

## LAYERED STYLES
Some styles, (currently the msglist_* and dirlist_* ones) are applied in layers. If a style differs from the base (in this case *list_default) then that style applies, unless overridden by a higher layer. If fg and bg colors are not defined explicitly (or defined to the default color) they will be considered as "transparent" and the colors from the lower layer will be used instead.

The order that msglist_* styles are applied in is, from first to last:

1.

msglist_default

2.

msglist_unread

3.

msglist_read

4.

msglist_answered

5.

msglist_forwarded

6.

msglist_flagged

7.

msglist_deleted

8.

msglist_result

9.

msglist_thread_folded

10.

msglist_thread_context

11.

msglist_thread_orphan

12.

msglist_marked

So, the marked style will override all other msglist styles.

The order for dirlist_* styles is:

1.

dirlist_default

2.

dirlist_unread

3.

dirlist_recent

## DYNAMIC MESSAGE LIST STYLES
All msglist_* styles can be defined for specific email header values. The syntax is as follows:

msglist_<name>.<header>,<header_value>.<attribute> = <attr_value>

If <header_value> starts with a tilde character ~, it will be interpreted as a regular expression. If you are writing regular expressions that try to match with . or . you need to wrap like this ~/<expression>/.

<header>,<header_value> can be specified multiple times to narrow down matches to more than one email header value. In that case, all given headers must match for the dynamic style to apply.

Examples:

```
msglist*.X-Sourcehut-Patchset-Update,APPROVED.fg = green
msglist*.X-Sourcehut-Patchset-Update,NEEDS_REVISION.fg = yellow
msglist*.X-Sourcehut-Patchset-Update,REJECTED.fg = red
"msglist_*.Subject,~^(\[[w-]+]\s*)?\[(RFC )?PATCH.fg" = #ffffaf
"msglist_*.Subject,~^(\[[w-]+]\s*)?\[(RFC )?PATCH.selected.fg" = #ffffaf
"msglist_*.From,~^Bob.Subject,~^(\[[w-]+]\s*)?\[(RFC )?PATCH.selected.fg" = #ffffaf
"msglist_*.List-ID,~/lists.sr.ht/selected.fg" = blue
```

When a dynamic style is matched to an email header, it will be used in priority compared to its non-dynamic counterpart. Provided the following styleset:

```
msglist_marked.fg = blue
msglist_*.Subject,~foobar.fg = red
```

An email with foobar in its subject will be colored in red all the time, since msglist_* also applies to msglist_marked.

When multiple <header>,<header_value> pairs are given, the last style which matches all given patterns will be applied. Provided the following styleset:

```
msglist_*.From,~^Bob.Subject,~foobar.fg = red
msglist_*.From,~^Bob.fg = blue
```

An email from Bob with foobar in its subject will be colored in blue, since the second style is a full match too.

## COLORS
The color values are set using any of the following methods:

default

The color is set as per the system or terminal default.

<Color name>

Any w3c approved color name is used to set colors for the style.

<Hex code>

Hexcode for a color can be used. The format must be #XXXXXX.

<Dec number>

Color based on the terminal palette index. Valid numbers are between 0 and 255.

## DEFAULTS
Before parsing a styleset, it is first initialized with the following defaults:

```
*.selected.bg = 12
*.selected.fg = 15
*.selected.bold = true
statusline_*.dim = true
*warning.dim = false
*warning.bold = true
*warning.fg = 11
*success.dim = false
*success.bold = true
*success.fg = 10
*error.dim = false
*error.bold = true
*error.fg = 9
border.bg = 12
border.fg = 15
title.bg = 12
title.fg = 15
title.bold = true
header.fg = 4
header.bold = true
msglist_unread.bold = true
msglist_deleted.dim = true
msglist_marked.bg = 6
msglist_marked.fg = 15
msglist_pill.bg = 12
msglist_pill.fg = 15
part_mimetype.fg = 12
selector_chooser.bold = true
selector_focused.bold = true
selector_focused.bg = 12
selector_focused.fg = 15
completion_*.bg = 8
completion_pill.bg = 12
completion_default.fg = 15
completion_description.fg = 15
completion_description.dim = true
[viewer]
url.underline = true
url.fg = 3
header.bold = true
header.fg = 4
signature.dim = true
signature.fg = 4
diff_meta.bold = true
diff_chunk.fg = 6
diff_chunk_func.fg = 6
diff_chunk_func.dim = true
diff_add.fg = 2
diff_del.fg = 1
quote_1.fg = 6
quote_2.fg = 4
quote_3.fg = 6
quote_3.dim = true
quote_4.fg = 4
quote_4.dim = true
quote_x.fg = 5
quote_x.dim = true
```

You can choose either to reset everything (except in the [viewer] section) by starting your styleset with these two lines:

```
*.default=true
*.normal=true
```

Or selectively override style object attributes.

If you want to also reset the [viewer] section, you need to insert the same two lines:

```
[viewer]
*.default=true
*.normal=true
```

## SEE ALSO
aerc(1) aerc-config(5)

## AUTHORS
Originally created by Drew DeVault and maintained by Robin Jarry who is assisted by other open source contributors. For more information about aerc development, see https://sr.ht/~rjarry/aerc/.


aerc-templates

title: aerc-templates(7)

text:
# aerc-templates(7)

## NAME
aerc-templates - template file specification for aerc(1)

## SYNOPSIS
aerc uses the go text/template package for the template parsing. Refer to the go text/template documentation for the general syntax. The template syntax described below can be used for message template files and for dynamic formatting of some UI app.

Template files are composed of headers, followed by a newline, followed by the body text.

Example:

```
X-Clacks-Overhead: GNU Terry Pratchett
Hello,
Greetings,
Chuck
```

If you have a template that doesn't add any header, it must be preceded by a newline, to avoid parsing parts of the body as header text.

All headers defined in the template will have precedence over any headers that are initialized by aerc (e.g. Subject, To, From, Cc) when composing a new message, forwarding or replying.

## MESSAGE DATA
The following data can be used in templates. Though they are not all available always.

Addresses

An array of mail.Address. That can be used to add sender or recipient names to the template.

- {{.From}}: List of senders.

- {{.Peer}}: List of senders or To recipients if the message is from you.

- {{.To}}: List of To recipients. Not always Available.

- {{.ReplyTo}}: List of ReplyTo recipients. Not always Available.

- {{.Cc}}: List of Cc recipients. Not always Available.

- {{.Bcc}}: List of Cc recipients. Not always Available.

- {{.OriginalFrom}}: List of senders of the original message. Available for quoted reply and forward.

Example:

Get the name of the first sender.

```
{{(index .From 0).Name}}
{{index (.From | names) 0}}
```

Get the email address of the first sender.

```
{{(index .From 0).Address}}
```

Date and Time

The date and time information is always available and can be easily formatted.

- {{.Date}}: Date and time information when the compose window is opened.

- {{.OriginalDate}}: Date and time when the original message was received. Available for quoted reply and forward.

To format the date fields, dateFormat and .Local are provided. Refer to the TEMPLATE FUNCTIONS section for details.

Subject

The subject of the email (ThreadPrefix will be empty unless threading is enabled).

```
{{.ThreadPrefix}}{{if .ThreadFolded}}{{printf "{%d}" .ThreadCount}}{{end}}{{.Subject}}
```

The subject of the email stripped of any Re: and Fwd: prefixes.

```
{{.SubjectBase}}
```

Threading When threading is enabled, these attributes are available in the message list: ThreadPrefix

If the message is part of a thread, this will contain arrows that represent the message tree based on In-Reply-To and References headers.

ThreadFolded

Will be true if the message has thread children which are hidden by :fold.

ThreadCount

The number of messages in the thread.

ThreadUnread

The number of unread messages in the thread.

Flags

List of message flags, not available when composing, replying nor forwarding. This is a list of strings that may be converted to a single string with join.

```
{{.Flags | join ""}}
```

IsReplied, IsForwarded, HasAttachment, IsFlagged, IsRecent, IsUnread, IsMarked, IsDraft

Individual boolean flags. not available when composing, replying nor forwarding.

```
{{if .IsFlagged}}★{{end}}
```

Labels

Message labels (for example notmuch tags). Not available when composing, replying nor forwarding. This is a list of strings that may be converted to a single string with join.

```
{{.Labels | join " "}}
```

Size

The size of the message in bytes. Not available when composing, replying nor forwarding. It can be formatted with humanReadable.

```
{{.Size | humanReadable}}
```

Filename

The full path of the message file. Not available when composing, replying nor forwarding. For the notmuch backend, it returns a random filename if there are multiple files associated with the message.

Filenames

A list of the full paths of the files associated with the message. For maildir this is always a list with a single element. Not available when composing, replying nor forwarding.

Any header value

Any header value of the email.

```
{{.Header "x-foo-bar"}}
```

Any header values of the original forwarded or replied message:

```
{{.OriginalHeader "x-foo-bar"}}
```

Message-ID The message-ID of the message.

```
:term b4 am {{.MessageId}}
```

MIME Type

MIME type is available for quoted reply and forward.

•

{{.OriginalMIMEType}}: MIME type info of quoted mail part. Usually text/plain or text/html.

Original Message

When using quoted reply or forward, the original message is available in a field called OriginalText.

```
{{.OriginalText}}
```

Signature

The signature of the currently selected account obtained from signature-file or signature-cmd.

```
{{.Signature}}
```

Account info

The current account name:

```
{{.Account}}
```

The current account's backend:

```
{{.AccountBackend}}
```

The current account's from address:

```
{{.AccountFrom}}
{{.AccountFrom.Address}}
```

Currently selected mailbox folder:

```
{{.Folder}}
```

Current message counts for all folders:

```
{{.Recent}} {{.Unread}} {{.Exists}}
{{.RUE}}
```

The new message status for the account. New messages are such that have arrived since the account tab last had focus. The flag is currently only set when aerc is running at the time of the arrival, i. e. message that have arrived while aerc was not running will not be indicated.

```
{{.HasNew}}
```

IANA role of the mailbox, converted to lowercase:

```
{{.Role}}
```

aerc implements two additional custom roles: A 'query' role is given to folders from a notmuch query-map and 'virtual' indicates a virtual node in the directory tree listing:

```
{{if eq .Role "query"}}{{...}}{{else}}{{...}}{{end}}
```

Current message counts for specific folders:

```
{{.Recent "inbox"}}
{{.Unread "inbox" "aerc/pending"}}
{{.Exists "archive" "spam" "foo/baz" "foo/bar"}}
{{.RUE "inbox"}}
```

Status line

The following data will only be available in the status line templates: Connection state.

```
{{.Connected}}
{{.ConnectionInfo}}
```

General status information (e.g. filter, search) separated with [statusline].separator.

```
{{.ContentInfo}}
```

Combination of {{.ConnectionInfo}} and {{.StatusInfo}} separated with [statusline].separator.

```
{{.StatusInfo}}
```

General on/off information (e.g. passthrough, threading, sorting, visual mode), separated with [statusline].separator.

```
{{.TrayInfo}}
```

Currently pressed key sequence that does not match any key binding and/or is incomplete.

```
{{.PendingKeys}}
```

Terminal

The following can only be used in the terminal tab title template: Bell state indicating whether the bell was rung since the terminal tab last had focus.

```
{{.Bell}}
```

Title of the terminal. This is typically what the program running in the terminal requests it to be or the name of the command.

```
{{.Title}}
```

## TEMPLATE FUNCTIONS
Besides the standard functions described in go's text/template documentation, aerc provides the following additional functions:

wrap

Wrap the original text to the specified number of characters per line.

```
{{wrap 72 .OriginalText}}
```

quote

Prepends each line with "> ".

```
{{quote .OriginalText}}
```

trimSignature

Removes the signature froma passed in mail. Quoted signatures are kept as they are.

```
{{trimSignature .OriginalText}}
```

join

Join the provided list of strings with a separator:

```
{{.To | names | join ", "}}
```

split

Split a string into a string slice with a separator:

```
{{.To | names | join ", " | split ", "}}
```

names

Extracts the names part from a mail.Address list. If there is no name available, the mbox (email address without @domain) is returned instead.

```
{{.To | names | join ", "}}
{{index (.To | names) 0}}
```

firstnames

Extracts the first names part from a mail.Address list. If there is no name available, the short mbox (start of email address without @domain) is returned instead.

```
{{.To | firstnames | join ", "}}
{{index (.To | firstnames) 0}}
```

initials

Extracts the initials from the names part from a mail.Address list. If there is no name available, the first letter of the email address is returned instead.

```
{{.To | initials | join ", "}}
{{index (.To | initials) 0}}
```

emails

Extracts the addresses part from a mail.Address list.

```
{{.To | emails | join ", "}}
{{index (.To | emails) 0}}
```

mboxes

Extracts the mbox part from a mail.Address list (i.e. smith from smith@example.com).

```
{{.To | mboxes | join ", "}}
{{index (.To | mboxes) 0}}
```

shortmboxes

Extracts the short mbox part from a mail.Address list (i.e. smith from smith.and.wesson@example.com).

```
{{.To | shortmboxes | join ", "}}
{{index (.To | shortmboxes) 0}}
```

persons

Formats a list of mail.Address into a list of strings containing the human readable form of RFC5322 (e.g. Firstname Lastname <email@address.tld>).

```
{{.To | persons | join ", "}}
{{index (.To | persons) 0}}
```

.Attach

Attaches a file to the message being composed.

```
{{.Attach '/usr/libexec/aerc/filters/html'}}
```

exec

Execute external command, provide the second argument to its stdin. The command is executed with the same search $PATH than aerc filters (see aerc-config(5) in the FILTERS section for more details).

```
{{exec `html` .OriginalText}}
```

.Local

Convert the date to the local timezone as specified by the locale.

```
{{.Date.Local}}
```

dateFormat

Format date and time according to the format passed as the second argument. The format must be specified according to go's time package format.

```
{{dateFormat .Date "Mon Jan 2 15:04:05 -0700 MST 2006"}}
```

You can also use the .DateAutoFormat method to format the date according to *-time*format settings:

```
{{.DateAutoFormat .OriginalDate.Local}}
```

now

Return the current date as a golang time.Time object that can be formatted with dateFormat.

```
{{dateFormat now "Mon Jan 2 15:04:05 -0700 MST 2006"}}
```

humanReadable

Return the human readable form of an integer value.

```
{{humanReadable 3217653721}}
```

cwd

Return the current working directory with the user home dir replaced by ~.

```
{{cwd}}
```

compactDir

Reduce a directory path into a compact form. The directory name will be split with / and each part will be reduced to the first letter in its name: INBOX/01_WORK/PROJECT will become I/W/PROJECT.

```
{{compactDir .Folder}}
```

contains

Checks if a string contains a substring.

```
{{contains "<!DOCTYPE html>" .OriginalText}}
```

hasPrefix

Checks if a string has a prefix.

```
{{hasPrefix "Business" .Folder}}
```

toLower

Convert a string to lowercase.

```
{{toLower "SPECIAL OFFER!"}}
```

toUpper

Convert a string to uppercase.

```
{{toUpper "important"}}
```

replace

Perform a regular expression substitution on the passed string.

```
{{replace `(.+) - .+ at .+..+` `$1` ((index .OriginalFrom 0).Name)}}
```

head

Return first n characters from string.

```
{{"hello" | head 2}}
```

tail

Return last n characters from string.

```
{{"hello" | tail 2}}
```

.Style

Apply a user-defined style (see aerc-stylesets(7)) to a string.

```
{{.Style .Account "red"}}
{{.Style .ThreadPrefix "thread"}}{{.Subject}}
```

.StyleSwitch

Apply a user-defined style (see aerc-stylesets(7)) to a string if it matches one of the associated regular expressions. If the string does not match any of the expressions, leave it unstyled.

```
{{.StyleSwitch .Subject (`^([[w-]+]s*)?[(RFC )?PATCH` "cyan")}}
{{.StyleSwitch (.From | names | join ", ") (case `Tim` "cyan") (case `Robin` "pink-blink") (default "blue")}}
```

.StyleMap

Apply user-defined styles (see aerc-stylesets(7)) to elements of a string list. The logic is the same than .StyleSwitch but works on a list of elements. An additional exclude option is available to remove the matching elements from the list.

```
{{.StyleMap .Labels (exclude .Folder) (exclude `^spam$`) (case `^inbox$` "red") (case `^Archive/.*` "green") (default "blue") | join " "}}
```

version

Returns the version of aerc, which can be useful for things like X-Mailer.

```
X-Mailer: aerc {{version}}
```

match

Check if a string matches a regular expression. This is intended for use in conditional control flow:

```
{{if match .Folder `.*/Archive-[0-9]+`}}{{humanReadable .Unread}}{{end}}
```

switch

Do switch/case/default control flows. The switch value is compared with regular expressions. If none of the case/default arms match, an empty string is returned.

```
{{switch .Folder (case `^INBOX$` "📥") (case `^Archive/.*` "🗃") (default "📁")}}
```

map

Transform a string list into another one. The logic is the same than switch but works on a list of elements. An additional exclude option is available to remove the matching elements from the list.

```
{{map .Labels (exclude .Folder) (exclude `^spam$`) (case `^inbox$` "📥") (case `^Archive/.*` "🗃") | join " "}}
```

Function chaining

All of the template functions can be chained together if needed. Example: Automatic HTML parsing for text/html mime type messages

```
{{if eq .OriginalMIMEType "text/html"}}
{{exec `/usr/libexec/aerc/filters/html` .OriginalText | wrap 72 | quote}}
{{else}}
{{wrap 72 .OriginalText | trimSignature | quote}}
{{end}}
```

## SEE ALSO
aerc(1) aerc-config(5)

## AUTHORS
Originally created by Drew DeVault and maintained by Robin Jarry who is assisted by other open source contributors. For more information about aerc development, see https://sr.ht/~rjarry/aerc/.


aerc-tutorial

title: aerc-tutorial(7)

text:
# aerc-tutorial(7)

## NAME
aerc-tutorial - tutorial for aerc(1)

## INTRODUCTION
Welcome to aerc! This tutorial will guide you through your first steps in using the client. This tutorial is a man page - you can read it again later with :help tutorial from aerc, or man aerc-tutorial from your terminal.

First, let's introduce some basic keybindings. For convention, we'll use <C-p> to represent Ctrl+p, which matches the convention used for writing keybindings for aerc.

<C-p>, <C-n>

Cycles to the previous or next tab

Try using these now to switch between your message list and the tutorial. In your message list, we use vim-style keys to get around.

k, j

Scrolls up and down between messages

<C-u>, <C-d>

Scrolls half a page up or down

g, G

Selects the first or last message, respectively

K, J

Switches between folders in the sidebar

<Enter>

Opens the selected message

You can also search the selected folder with /, or filter with \ . When searching you can use n and p to jump to the next and previous result. Filtering hides any non-matching message.

## THE MESSAGE VIEWER
Press <Enter> to open a message. By default, the message viewer will display your message using less(1). This should also have familiar, vim-like keybindings for scrolling around in your message.

Multipart messages (messages with attachments, or messages with several alternative formats) show a part selector on the bottom of the message viewer.

<C-k>, <C-j>

Cycle between parts of a multipart message

q

Close the message viewer

To show HTML messages parts, the text/html filter in your aerc.conf file (which is probably in ~/.config/aerc/) requires w3m along with optional dependencies for safer network isolation: unshare (from util-linux) or socksify (from dante-utils).

You can also do many tasks you could do in the message list from here, like replying to emails, deleting the email, or view the next and previous message (J and K).

## COMPOSING MESSAGES
Return to the message list by pressing q to dismiss the message viewer. Once there, let's compose a message.

C

Compose a new message

rr

Reply-all to a message

rq

Reply-all to a message, and pre-fill the editor with a quoted version of the message being replied to

Rr

Reply to a message

Rq

Reply to a message, and pre-fill the editor with a quoted version of the message being replied to

For now, let's use C to compose a new message. The message composer will appear. You should see To, From, and Subject lines, as well as your editor. You can use <Tab> or <C-j> and <C-k> to cycle between these fields (tab won't cycle between fields once you enter the editor, but <C-j> and <C-k> will).

Let's send an email to yourself. Note that the To and From headers expect RFC 5322 addresses, e.g. John Doe <john@example.org>, or simply <john@example.org>. Separate multiple recipients with commas. Go ahead and fill out an email, then close the editor.

The message review screen is shown next. You have a chance now to revise the email before it's sent. Press y to send the email if it looks good.

Note: when using the terminal in the message view, you can summon aerc's ex command line by using <C-x>. : is sent to the editor.

## USING THE TERMINAL
aerc comes with an embedded terminal, which you've already used to view and edit emails. We can also use this for other purposes, such as referencing a git repository while reviewing a patch. From the message list, we can use the following keybindings to open a terminal:

<C-t>

Opens a new terminal tab, running your shell

$, !

Prompts for a command to run, then opens a new terminal tab running that command

|

Prompts for a command to run, then pipes the selected email into that command and displays the result on a new terminal tab

Try pressing $ and entering top. You can also use the :cd command to change aerc's working directory, and the directory in which new terminals run. Use :pwd to see it again if you're not sure where you are.

## ADDITIONAL NOTES

### COMMANDS
Every keybinding is ultimately bound to an aerc command. You can also summon the command line by pressing :, then entering one of these commands. See aerc(1) or :help for a full list of commands.

### MESSAGE FILTERS
When displaying messages in the message viewer, aerc will pipe them through a message filter first. This allows you to decode messages in non-plaintext formats, add syntax highlighting, etc. aerc ships with a few default filters:

- text/plain parts are piped through the colorize built-in filter which handles URL, quotes and diff coloring.

- text/calendar is processed to be human readable text

- text/html (disabled by default) can be uncommented to pipe through the built-in html filter.

### CUSTOMIZING AERC
Aerc is highly customizable. Review aerc-config(5) (or use :help config) to learn more about how to add custom keybindings, install new message filters, change its appearance and behavior, and so on.

## AUTHORS
Originally created by Drew DeVault and maintained by Robin Jarry who is assisted by other open source contributors. For more information about aerc development, see https://sr.ht/~rjarry/aerc/.


package: alsa-utils

title: alsactl_init(7)

summary: alsa control management \- initialization

text:
# alsactl_init(7)

## NAME
alsactl_init - alsa control management - initialization

## DESCRIPTION
"alsactl init" provides soundcard specific initialization.

## CONFIGURATION
All "alsactl init" configuration files are placed in /usr/share/alsa/init/ directory. The top level configuration file is /usr/share/alsa/init/00main. The default top-level file can be also specified using -i or --initfile parameter for the alsactl tool. Every file consists of a set of lines of text. All empty lines or lines beginning with '#' will be ignored.

### Rules files
The "alsactl init" rules are read from the files located in the /usr/share/alsa/init/*. The top level configuration file is /usr/share/alsa/init/00main. Every line in the rules file contains at least one key value pair. There are two kind of keys, match and assignment keys. If all match keys are matching against its value, the rule gets applied and the assign keys get the specified value assigned.

A rule may consists of a list of one or more key value pairs separated by a comma. Each key has a distinct operation, depending on the used operator. Valid operators are:

==

Compare for equality.

!=

Compare for non-equality.

=

Assign a value to a key. Keys that represent a list, are reset and only this single value is assigned.

+=

Add the value to a key that holds a list of entries.

:=

Assign a value to a key finally; disallow any later changes, which may be used to prevent changes by any later rules.

The following key names can be used to match against device properties:

CARDINDEX

Match the card index of the ALSA driver.

CTL{attribute}

Set or test universal control attribute. Possible attributes: numid

Numeric control identification.

iface, interface

Control interface name (CARD, HWEDEP, MIXER, PCM, RAWMIDI, TIMER, SEQUENCER)

subdev, subdevice

Subdevice number.

name

Control name

index

Control index

type

Control type (BOOLEAN, INTEGER, INTEGER64, ENUMERATED, BYTES, IEC958)

attr, attribute

Attributes (stored in a string - use match characters * and ?): r

control is readable

w

control is writable

v

control is volatile

i

control is inactive

l

control is locked

R

control is TLV readable

W

control is TLV writable

C

control is TLV commandable

o

process is owner of this control

u

control created in user space

owner

Control owner process PID number

count

Control count of values

min

Value range - minimum value

max

Value range - maximum value

step

Value range - step value

dBmin

Value range - minimum dB value

dBmax

Value range - maximum dB value

items

Enumerated value - number of text items

enums

Enumerated value - list of text names stored between '|' character

value

Value of control stored to a string delimited by comma (,).

do_search

Search for a control. Value "1" is returned if a control was found. The CTL{name} key might contain match characters * and ?. An control index might be specified as first argument starting from zero (e.g. CTL{do_search 2}="1").

do_count

Search for a controls and return total count of matched ones. The CTL{name} key might contain match characters * and ?.

CONFIG{sysfs_device}

The relative path to sysfs subsystem specifying the root directory of a soundcard device. Usually, it should be set to "/class/sound/card$cardinfo{card}/device".

ATTR{filename}

Match sysfs attribute values of the soundcard device. The relative path to sysfs tree must be defined by CONFIG{sysfs_device} key. Trailing whitespace in the attribute values is ignored, if the specified match value does not contain trailing whitespace itself. Depending on the type of operator, this key is also used to set the value of a sysfs attribute.

ENV{key}

Match against the value of an environment variable. Up to five ENV keys can be specified per rule. Depending on the type of operator, this key is also used to export a variable to the environment.

PROGRAM

Execute external program. The key is true, if the program returns without exit code zero. The whole event environment is available to the executed program. The program's output printed to stdout is available for the RESULT key. Several buildin commands are available:

__ctl_search

Search for a control. The CTL{name} key might contain match characters * and ?. An control index might be specified as first argument starting from zero (e.g. PROGRAM="__ctl_search 2").

__ctl_count

Search for a controls and return total count of matched ones. The CTL{name} key might contain match characters * and ?.

RESULT

Match the returned string of the last PROGRAM call. This key can be used in the same or in any later rule after a PROGRAM call.

Most of the fields support a shell style pattern matching. The following pattern characters are supported:

*

Matches zero, or any number of characters.

?

Matches any single character.

[]

Matches any single character specified within the brackets. For example, the pattern string 'tty[SR]' would match either 'ttyS' or 'ttyR'. Ranges are also supported within this match with the '-' character. For example, to match on the range of all digits, the pattern [0-9] would be used. If the first character following the '[' is a '!', any characters not enclosed are matched.

The following keys can get values assigned:

CTL{numid}, CTL{iface}, CTL{device}, CTL{subdev}, CTL{name}, CTL{index},

Select universal control element.

CTL{value}

Value is set (written) also to soundcard's control device and RESULT key is set to errno code. The result of set operation is always true (it means continue with next key on line).

CTL{values}

Value is set (written) also to soundcard's control device (all control values are set to specified value) and RESULT key is set to errno code. The result of set operation is always true (it means continue with next key on line).

CTL{write}

Value is set (written) also to soundcard's control device (all control values are set to specified value). The result of set operation is true when operation succeed (it means continue with next key on line).

ENV{key}

Export a variable to the environment. Depending on the type of operator, this key is also to match against an environment variable.

RESULT

Set RESULT variable. Note that PROGRAM also sets this variable, but setting this variable manually might be useful to change code execution order (included files).

LABEL

Named label where a GOTO can jump to.

GOTO

Jumps to the next LABEL with a matching name. The goto cannot jump backward.

INCLUDE

Include the specified filename or files in specified directory. When a directory is specified, only the files with the extension ".conf" are read. Also they are read in the alphabetical order. Thus it's highly recommended to use some number prefix (e.g. "01-something.conf") to assure the order of execucions.

ACCESS

Check if specified file or directory exists

CONFIG{sysfs_device}

The relative path to sysfs subsystem specifying the root directory of a soundcard device. Usually, it should be set to "/class/sound/card$cardinfo{card}/device".

PRINT

PRINT value to stdout.

ERROR

PRINT value to stderr.

EXIT

Exit immediately and set program exit code to value (should be integer). If value is "return" string, parser leaves current included file and returns to parent configuration file.

The PROGRAM, RESULT, CTL{value}, PRINT, ERROR, EXIT, CONFIG{} fields support simple printf-like string substitutions. It allows the use of the complete environment set by earlier matching rules. For all other fields, substitutions are applied while the individual rule is being processed. The available substitutions are:

$cardinfo{attribute}, %i{attribute}

See CARDINFO{} for more details.

$ctl{attribute}, %C{attribute}

See CTL{} for more details.

$attr{file}, %s{file}

The value of a sysfs attribute found at the device, where all keys of the rule have matched. If the attribute is a symlink, the last element of the symlink target is returned as the value.

$env{key}, %E{key}

The value of an environment variable.

$result, %c

The string returned by the external program requested with PROGRAM. A single part of the string, separated by a space character may be selected by specifying the part number as an attribute: %c{N}. If the number is followed by the '+' char this part plus all remaining parts of the result string are substituted: %c{N+}

$sysfsroot, %r

Root directory where sysfs file-system is mounted. Ususally, this value is just "/sys".

$config{key}, %g{key}

The value of a configuration variable. See CONFIG{} for more details.

%%

The '%' character itself.

$$

The '$' character itself.

The count of characters to be substituted may be limited by specifying the format length value. For example, '%3s{file}' will only insert the first three characters of the sysfs attribute

## AUTHOR
Written by Jaroslav Kysela <perex@perex.cz>

Some portions are written by Greg Kroah-Hartman <greg@kroah.com> and Kay Sievers <kay.sievers@vrfy.org>.

## SEE ALSO
alsactl(1)


amt-howto

package: amtterm

title: amt-howto(7)

text:
# amt-howto(7)

## NAME
amt-howto - Intel AMT with linux mini howto

## DESCRIPTION

### What is AMT and why I should care?
AMT stands for "Active Management Technology". It provides some remote management facilities. They are handled by the hardware and firmware, thus they work independant from the operation system. Means: It works before Linux bootet up to the point where it activated the network interface. It works even when your most recent test kernel deadlocked the machine. Which makes it quite useful for development machines ...

Intel AMT is part of the vPro Platform. Recent intel-chipset based business machines should have it. My fairly new Intel SDV machine has it too.

### Documentation
Look here for documentation beyond this mini howto:

http://www.intel.com/technology/platform-technology/intel-amt/

Most useful to get started: "Intel AMT Deployment and Reference Guide"

### Very short AMT enabling instructions.
Enter BIOS Setup.

* Enable AMT

Enter ME (Management Extention) Setup. Ctrl-P hotkey works for me.

* Login, factory default password is "admin".

* Change password. Trivial ones don't work, must include upper- and lowercase letters, digits, special characters.

* Enable AMT Managment.

Reboot, Enter ME Setup again with AMT enabled.

* Configure AMT (hostname, network config, ...)

* Use SMB (Small Business) management mode. The other one (Enterprise) requires Active Directory Service Infrastructure, you don't want that, at least not for your first steps ...

### Testing AMT
Take your browser, point it to http://machine:16992/. If you configured AMT to use DHCP (which is the default) the OS and the management stack share the same IP address.

You must do that from a remote host as the NIC intercepts network packets for AMT, thus it doesn't work from the local machine as the packets never pass the NIC then. If everything is fine you'll see a greeting page with a button for login.

You can login now, using "admin" as username and the password configured during setup. You'll see some pages with informations about the machine. You can also change AMT settings here.

### Control Machine
You might have noticed already while browing the pages: There is a "Remote Control" page. You can remotely reset and powercycle the machine there, thus recover the machine after booting a b0rken kernel, without having someone walk over to the machine and hit the reset button.

### Serial-over-LAN (SOL) console
AMT also provides a virtual serial port which can be accessed via network. That gives you a serial console without a serial cable to another machine.

If you have activated AMT and SOL the linux kernel should see an additional serial port, like this on my machine:

```
  [root@xeni ~]# dmesg | grep ttyS2

  0000:00:03.3: ttyS2 at I/O 0xe000 (irq = 169) is a 16550A
```

Edit initab, add a line like this:

```
  S2:2345:respawn:/sbin/agetty ttyS2 115200 vt100-nav
```

You should add the serial port to /etc/securetty too so you are able to login as root. Reload inittab ("init q"). Use amtterm to connect. Tap enter. You should see a login prompt now and be able to login.

You can also use that device as console for the linux kernel, using the usual "console=ttyS2,115200" kernel command line argument, so you see the boot messages (and kernel Oopses, if any).

You can tell grub to use that serial device, so you can pick a working kernel for the next boot. Usual commands from the grub manual, except that you need "--port=0xe000" instead of "--unit=0" due to the non-standard I/O port for the serial line (my machine, yours might use another port, check linux kernel boot messages).

The magic command for the Xen kernel is "com1=115200,8n1,0xe000,0" (again, you might have to replace the I/O port). The final '0' disables the IRQ, otherwise the Xen kernel hangs at boot after enabling interrupts.

### Fun with Xen and AMT
The AMT network stack seems to become slightly confused when running on a Xen host in DHCP mode. Everything works fine as long as only Dom0 runs. But if one starts a guest OS (with bridged networking) AMT suddenly changes the IP address to the one the guest aquired via DHCP.

It is probably a good idea to assign a separate static IP address to AMT then. I didn't manage to switch my machine from DHCP to static IP yet though, the BIOS refuses to accept the settings. The error message doesn't indicate why.

### More fun with AMT
You might want to download the DTK (Developer Toolkit, source code is available too) and play with it. The .exe is a self-extracting rar archive and can be unpacked on linux using the unrar utility. The Switchbox comes with a linux binary (additionally to the Windows stuff). The GUI tools are written in C#. Trying to make them fly with mono didn't work for me though (mono version 1.2.3 as shipped with Fedora 7).

## SEE ALSO
amtterm(1), gamt(1), amttool(1)

http://www.intel.com/technology/platform-technology/intel-amt/

## WRITTEN BY
Gerd Hoffmann <kraxel@redhat.com>


apparmor

package: apparmor

title: apparmor(7)

text:
# apparmor(7)

## NAME
AppArmor - kernel enhancement to confine programs to a limited set of resources.

## DESCRIPTION
AppArmor is a kernel enhancement to confine programs to a limited set of resources. AppArmor's unique security model is to bind access control attributes to programs rather than to users.

AppArmor confinement is provided via profiles loaded into the kernel via apparmor_parser(8), typically through the apparmor.service systemd unit, which is used like this:

```
        # systemctl start apparmor
        # systemctl reload apparmor
```

AppArmor can operate in two modes: enforcement, and complain or learning:

- enforcement - Profiles loaded in enforcement mode will result in enforcement of the policy defined in the profile as well as reporting policy violation attempts to syslogd.

- complain - Profiles loaded in "complain" mode will not enforce policy. Instead, it will report policy violation attempts. This mode is convenient for developing profiles. To manage complain mode for individual profiles the utilities aa-complain(8) and aa-enforce(8) can be used. These utilities take a program name as an argument.

Profiles are traditionally stored in files in /etc/apparmor.d/ under filenames with the convention of replacing the / in pathnames with . (except for the root /) so profiles are easier to manage (e.g. the /usr/sbin/nscd profile would be named usr.sbin.nscd).

Profiles are applied to a process at exec(3) time (as seen through the execve(2) system call): once a profile is loaded for a program, that program will be confined on the next exec(3). If a process is already running under a profile, when one replaces that profile in the kernel, the updated profile is applied immediately to that process. On the other hand, a process that is already running unconfined cannot be confined.

AppArmor supports the Linux kernel's securityfs filesystem, and makes available the list of the profiles currently loaded; to mount the filesystem:

```
        # mount -tsecurityfs securityfs /sys/kernel/security
        $ cat /sys/kernel/security/apparmor/profiles
        /usr/bin/mutt
        /usr/bin/gpg
           ...
```

Normally, the initscript will mount securityfs if it has not already been done.

AppArmor also restricts what privileged operations a confined process may execute, even if the process is running as root. A confined process cannot call the following system calls:

```
        create_module(2) delete_module(2) init_module(2) ioperm(2)
        iopl(2) ptrace(2) reboot(2) setdomainname(2)
        sethostname(2) swapoff(2) swapon(2) sysctl(2)
```

### Complain mode
Instead of denying access to resources the profile does not have a rule for AppArmor can "allow" the access and log a message for the operation that triggers it. This is called complain mode. It is important to note that rules that are present in the profile are still applied, so allow rules will still quiet or force audit messages, and deny rules will still result in denials and quieting of denial messages (see Turn off deny audit quieting if this is a problem).

Complain mode can be used to develop profiles incrementally as an application is exercised. The logged accesses can be added to the profile and then can the application further exercised to discover further additions that are needed. Because AppArmor allows the accesses the application will behave as it would if AppArmor was not confining it.

Warning complain mode does not provide any security, only auditing, while it is enabled. It should not be used in a hostile environment or bad behaviors may be logged and added to the profile as if they are resource accesses that should be used by the application.

Note complain mode can be very noisy with new or empty profiles, but with developed profiles might not log anything if the profile covers the application behavior well. See Audit Rate Limiting if complain mode is generating too many log messages.

To set a profile and any children or hat profiles the profile may contain into complain mode use

```
        aa-complain /etc/apparmor.d/<the-application>
```

To manually set a specific profile in complain mode, add the "complain" flag, and then manually reload the profile:

```
        profile foo flags=(complain) { ... }
```

Note that the "complain" flag must also be added manually to any hats or children profiles of the profile or they will continue to use the previous mode.

To enable complain mode globally, run:

```
        echo -n complain > /sys/module/apparmor/parameters/mode
```

or to set it on boot add:

```
        apparmor.mode=complain
```

as a kernel boot parameter.

Warning Setting complain mode globally disables all apparmor security protections. It can be useful during debugging or profile development, but setting it selectively on a per profile basis is safer.

## ERRORS
When a confined process tries to access a file it does not have permission to access, the kernel will report a message through audit, similar to:

```
        audit(1386511672.612:238): apparmor="DENIED" operation="exec"
          parent=7589 profile="/tmp/sh" name="/bin/uname" pid=7605
          comm="sh" requested_mask="x" denied_mask="x" fsuid=0 ouid=0
        audit(1386511672.613:239): apparmor="DENIED" operation="open"
          parent=7589 profile="/tmp/sh" name="/bin/uname" pid=7605
          comm="sh" requested_mask="r" denied_mask="r" fsuid=0 ouid=0
        audit(1386511772.804:246): apparmor="DENIED" operation="capable"
          parent=7246 profile="/tmp/sh" pid=7589 comm="sh" pid=7589
          comm="sh" capability=2  capname="dac_override"
```

The permissions requested by the process are described in the operation= and denied_mask= (for files - capabilities etc. use a slightly different log format). The "name" and process id of the running program are reported, as well as the profile name including any "hat" that may be active, separated by "//". ("Name" is in quotes, because the process name is limited to 15 bytes; it is the same as reported through the Berkeley process accounting.)

For confined processes running under a profile that has been loaded in complain mode, enforcement will not take place and the log messages reported to audit will be of the form:

```
        audit(1386512577.017:275): apparmor="ALLOWED" operation="open"
          parent=8012 profile="/usr/bin/du" name="/etc/apparmor.d/tunables/"
          pid=8049 comm="du" requested_mask="r" denied_mask="r" fsuid=1000 ouid=0
        audit(1386512577.017:276): apparmor="ALLOWED" operation="open"
          parent=8012 profile="/usr/bin/du" name="/etc/apparmor.d/tunables/"
          pid=8049 comm="du" requested_mask="r" denied_mask="r" fsuid=1000 ouid=0
```

If the userland auditd is not running, the kernel will send audit events to klogd; klogd will send the messages to syslog, which will log the messages with the KERN facility. Thus, REJECTING and PERMITTING messages may go to either /var/log/audit/audit.log or /var/log/messages, depending upon local configuration.

## DEBUGGING
AppArmor provides a few facilities to log more information, which can help debugging profiles.

### Enable debug mode
When debug mode is enabled, AppArmor will log a few extra messages to dmesg (not via the audit subsystem). For example, the logs will tell whether environment scrubbing has been applied.

To enable debug mode, run:

```
        echo 1 > /sys/module/apparmor/parameters/debug
```

or to set it on boot add:

```
        apparmor.debug=1
```

as a kernel boot parameter.

### Turn off deny audit quieting
By default, operations that trigger "deny" rules are not logged. This is called deny audit quieting.

To turn off deny audit quieting, run:

```
        echo -n noquiet >/sys/module/apparmor/parameters/audit
```

or to set it on boot add:

```
        apparmor.audit=noquiet
```

as a kernel boot parameter.

### Force audit mode
AppArmor can log a message for every operation that triggers a rule configured in the policy. This is called force audit mode.

Warning! Force audit mode can be extremely noisy even for a single profile, let alone when enabled globally.

To set a specific profile in force audit mode, add the "audit" flag:

```
        profile foo flags=(audit) { ... }
```

To enable force audit mode globally, run:

```
        echo -n all > /sys/module/apparmor/parameters/audit
```

or to set it on boot add:

```
        apparmor.audit=all
```

as a kernel boot parameter.

Audit Rate Limiting

If auditd is not running, to avoid losing too many of the extra log messages, you will likely have to turn off rate limiting by doing:

```
        echo 0 > /proc/sys/kernel/printk_ratelimit
```

But even then the kernel ring buffer may overflow and you might lose messages.

Else, if auditd is running, see auditd(8) and auditd.conf(5).

## FILES
/etc/apparmor.d/

/var/cache/apparmor/

/var/log/audit/audit.log

/var/log/messages

## SEE ALSO
apparmor_parser(8), aa_change_hat(2), apparmor.d(5), aa-autodep(1), clean(1), auditd(8), aa-unconfined(8), aa-enforce(1), aa-complain(1), and <https://wiki.apparmor.net>.


title: apparmor_xattrs(7)

summary: AppArmor profile xattr(7) matching

text:
# apparmor_xattrs(7)

## NAME
apparmor_xattrs - AppArmor profile xattr(7) matching

## DESCRIPTION
AppArmor profiles can conditionally match files based on the presence and value of extended attributes in addition to file path. The following profile applies to any file under "/usr/bin" where the "security.apparmor" extended attribute has the value "trusted":

```
        profile trusted /usr/bin/* xattrs=(security.apparmor="trusted") {
                # ...
        }
```

Note that "security.apparmor" and "trusted" are arbitrary, and profiles can match based on the value of any attribute.

The xattrs value may also contain a path regex:

```
        profile trusted /usr/bin/* xattrs=(user.trust="tier/*") {
                # ...
        }
```

The getfattr(1) and setfattr(1) tools can be used to view and manage xattr values:

```
        $ setfattr -n 'security.apparmor' -v 'trusted' /usr/bin/example-tool
        $ getfattr --absolute-names -d -m - /usr/bin/example-tool
        # file: usr/bin/example-tool
        security.apparmor="trusted"
```

The priority of each profile is determined by the length of the path, then the number of xattrs specified. A more specific path is preferred over xattr matches:

```
        # Highest priority, longest path.
        profile example1 /usr/bin/example-tool {
                # ...
        }
        # Lower priority than the longer path, but higher priority than a rule
        # with fewer xattr matches.
        profile example2 /usr/** xattrs=(
                security.apparmor="trusted"
                user.domain="**"
        ) {
                # ...
        }
        # Lowest priority. Same path length as the second profile, but has
        # fewer xattr matches.
        profile example2 /usr/** {
                # ...
        }
```

xattr matching requires the following kernel feature:

```
        /sys/kernel/security/apparmor/features/domain/attach_conditions/xattr
```

## KNOWN ISSUES
AppArmor profiles currently can't reliably match extended attributes with binary values such as security.evm and security.ima. In the future AppArmor may gain the ability to match based on the presence of certain attributes while ignoring their values.

## SEE ALSO
apparmor(8), apparmor_parser(8), apparmor.d(5), xattr(7), aa-autodep(1), clean(1), auditd(8), getfattr(1), setfattr(1), and <https://wiki.apparmor.net>.


atf

package: atf-tests

title: atf(7)

text:
# atf(7)

## NAME
ATF — introduction to the Automated Testing Framework

## DESCRIPTION
The Automated Testing Framework (ATF) is a collection of libraries to implement test programs in a variety of languages. These libraries all offer similar functionality and any test program written with them exposes a consistent user interface.

Test programs using the ATF libraries rely on a separate runtime engine to execute them in a deterministic fashion. The runtime engine isolates the test programs from the rest of the system and ensures some common side-effects are cleaned up. The runtime engine is also responsible for gathering the results of all tests and composing reports. The current runtime of choice is Kyua, described in kyua(1).

If your operating systems distributes ATF, it should also provide an introductory tests(7) manual page. You are encouraged to read it now.

The rest of this manual page serves as a cross-reference to all the other documentation shipped with ATF.

### Language bindings
atf-c(3)

C programming interface.

atf-c++(3)

C++ programming interface.

atf-sh(3)

sh(1) programming interface.

### Miscellaneous pages
atf-test-case(4)

Generic description of test cases, independent of the language they are implemented in.

atf-test-program(1)

Common interface provided by the test programs written using the ATF libraries.

## SEE ALSO
kyua(1), tests(7)

## HISTORY
ATF started as a Google Summer of Code 2007 project mentored by The NetBSD Foundation. Its original goal was to provide a testing framework for the NetBSD operating system, but it grew as an independent project because the framework itself did not need to be tied to a specific operating system.

Originally, ATF shipped the collection of libraries described in this manual page as well as a runtime engine. The runtime engine has since been replaced by Kyua and the old tools were removed in 0.20, which shipped in early 2014.

As of late 2014, both FreeBSD and NetBSD ship ATF in their base systems and provide extensive test suites based on it.

For more details on historical changes, refer to:

```
/usr/share/doc/atf/NEWS
```

## AUTHORS
For more details on the people that made ATF possible, refer to:

```
/usr/share/doc/atf/AUTHORS
```


audit.rules

package: audit

title: audit.rules(7)

text:
# audit.rules(7)

## NAME
audit.rules - a set of rules loaded in the kernel audit system

## DESCRIPTION
audit.rules is a file containing audit rules that will be loaded by the audit daemon's init script whenever the daemon is started. The auditctl program is used by the initscripts to perform this operation. The syntax for the rules is essentially the same as when typing in an auditctl command at a shell prompt except you do not need to type the auditctl command name since that is implied. The audit rules come in 3 varieties: control, file, and syscall.

### Control
Control commands generally involve configuring the audit system rather than telling it what to watch for. These commands typically include deleting all rules, setting the size of the kernel's backlog queue, setting the failure mode, setting the event rate limit, or to tell auditctl to ignore syntax errors in the rules and continue loading. Generally, these rules are at the top of the rules file.

### File System
File System rules are sometimes called watches. These rules are used to audit access to particular files or directories that you may be interested in. If the path given in a watch rule is a directory, then the rule used is recursive to the bottom of the directory tree excluding any directories that may be mount points. The syntax of these watch rules generally follow this format:

```
-a always,exit -F arch=b64 -F path=path-to-file -F perm=permissions -F key=keyname
```

where the permission are any one of the following:

r

- read of the file

w

- write to the file

x

- execute the file

a

- change in the file's attribute

For best performance, you should supply an arch field in the rule. The individual permissions will cause the selection of specific system calls that use that kind of access. Not supplying the arch will cause the selection of all system calls which will affect performance as all system calls will be evaluated.

Watches can also be created using the deprecated -w format which allows for backwards compatibility at the expense of system performance as explained. Using syscall rules as shown above, you can choose between path and dir which is against a specific inode or directory tree respectively. It should also be noted that the recursive directory watch will stop if there is a mount point below the parent directory. There is an option to make the mounted subdirectory equivalent by using a -q rule.

### System Call
The system call rules are loaded into a matching engine that intercepts each syscall that all programs on the system makes. Therefore it is very important to only use syscall rules when you have to since these affect performance. The more rules, the bigger the performance hit. You can help the performance, though, by combining syscalls into one rule whenever possible.

The Linux kernel has 6 rule matching lists or filters as they are sometimes called. They are: task, exit, user, exclude, filesystem, and io_uring. The task list is checked only during the fork or clone syscalls. It is rarely used in practice.

The exit filter is the place where all syscall and file system audit requests are evaluated.

The user filter is used to filter (remove) some events that originate in user space. By default, any event originating in user space is allowed. So, if there are some events that you do not want to see, then this is a place where some can be removed. See auditctl(8) for fields that are valid.

The exclude filter is used to exclude certain events from being emitted. The msgtype and a number of subject attribute fields can be used to tell the kernel which message types you do not want to record. This filter can remove the event as a whole and is not selective about any other attribute. The user and exit filters are better suited to selectively auditing events. The action is ignored for this filter, defaulting to "never".

The io_uring filter is used to watch underlying syscalls performed by io_uring operations.

Syscall rules take the general form of:

```
-a action,list -S syscall -F field=value -k keyname
```

The -a option tells the kernel's rule matching engine that we want to append a rule at the end of the rule list. But we need to specify which rule list it goes on and what action to take when it triggers. Valid actions are:

always

- always create an event

never

- never create an event

The action and list are separated by a comma but no space in between. Valid lists are: task, exit, user, exclude, filesystem, and io_uring. Their meaning was explained earlier.

Next in the rule would normally be the -S option. This field can either be the syscall name or number. For readability, the name is almost always used. You may give more than one syscall in a rule by specifying another -S option. When sent into the kernel, all syscall fields are put into a mask so that one compare can determine if the syscall is of interest. So, adding multiple syscalls in one rule is very efficient. When you specify a syscall name, auditctl will look up the name and get its syscall number. This leads to some problems on bi-arch machines. The 32 and 64 bit syscall numbers sometimes, but not always, line up. So, to solve this problem, you would generally need to break the rule into 2 with one specifying -F arch=b32 and the other specifying -F arch=b64. This needs to go in front of the -S option so that auditctl looks at the right lookup table when returning the number.

After the syscall is specified, you would normally have one or more -F options that fine tune what to match against. Rather than list all the valid field types here, the reader should look at the auditctl man page which has a full listing of each field and what it means. But it's worth mentioning a couple things.

The audit system considers uids to be unsigned numbers. The audit system uses the number -1 to indicate that a loginuid is not set. This means that when it's printed out, it looks like 4294967295. But when you write rules, you can use either "unset" which is easy to remember, or -1, or 4294967295. They are all equivalent. If you write a rule that you wanted try to get the valid users of the system, you need to look in /etc/login.defs to see where user accounts start. For example, if UID_MIN is 1000, then you would also need to take into account that the unsigned representation of -1 is higher than 500. So you would address this with the following piece of a rule:

```
-F auid>=1000 -F auid!=unset
```

These individual checks are "anded" and both have to be true.

The last thing to know about syscall rules is that you can add a key field which is a free form text string that you want inserted into the event to help identify its meaning. This is discussed in more detail in the NOTES section.

## NOTES
The purpose of auditing is to be able to do an investigation periodically or whenever an incident occurs. A few simple steps in planning up front will make this job easier. The best advice is to use keys in both the watches and system call rules to give the rule a meaning. If rules are related or together meet a specific requirement, then give them a common key name. You can use this during your investigation to select only results with a specific meaning.

When doing an investigation, you would normally start off with the main aureport output to just get an idea about what is happening on the system. This report mostly tells you about events that are hard coded by the audit system such as login/out, uses of authentication, system anomalies, how many users have been on the machine, and if SE Linux has detected any AVCs.

```
aureport --start this-week
```

After looking at the report, you probably want to get a second view about what rules you loaded that have been triggering. This is where keys become important. You would generally run the key summary report like this:

```
aureport --start this-week --key --summary
```

This will give an ordered listing of the keys associated with rules that have been triggering. If, for example, you had a syscall audit rule that triggered on the failure to open files with EPERM that had a key field of access like this:

```
-a always,exit -F arch=b64 -S open -S openat -S openat2 -F exit=-EPERM -k access
```

Then you can isolate these failures with ausearch and pipe the results to aureport for display. Suppose your investigation noticed a lot of the access denied events. If you wanted to see the files that unauthorized access has been attempted, you could run the following command:

```
ausearch --start this-week -k access --raw | aureport --file --summary
```

This will give an ordered list showing which files are being accessed with the EPERM failure. Suppose you wanted to see which users might be having failed access, you would run the following command:

```
ausearch --start this-week -k access --raw | aureport --user --summary
```

If your investigation showed a lot of failed accesses to a particular file, you could run the following report to see who is doing it:

ausearch --start this-week -k access -f /path-to/file --raw | aureport --user -i

This report will give you the individual access attempts by person. If you needed to see the actual audit event that is being reported, you would look at the date, time, and event columns. Assuming the event was 822 and it occurred at 2:30 on 09/01/2009 and you use the en_US.utf8 locale, the command would look something like this:

```
ausearch --start 09/01/2009 02:30 -a 822 -i --just-one
```

This will select the first event from that day and time with the matching event id and interpret the numeric values into human readable values.

The most important step in being able to do this kind of analysis is setting up key fields when the rules were originally written. It should also be pointed out that you can have more than one key field associated with any given rule.

## TROUBLESHOOTING
If you are not getting events on syscall rules that you think you should, try running a test program under strace so that you can see the syscalls. There is a chance that you might have identified the wrong syscall.

If you get a warning from auditctl saying, "32/64 bit syscall mismatch in line XX, you should specify an arch". This means that you specified a syscall rule on a bi-arch system where the syscall has a different syscall number for the 32 and 64 bit interfaces. This means that on one of those interfaces you are likely auditing the wrong syscall. To solve the problem, re-write the rule as two rules specifying the intended arch for each rule. For example,

```
-a always,exit -S openat -k access
```

would be rewritten as

```
-a always,exit -F arch=b32 -S openat -k access
-a always,exit -F arch=b64 -S openat -k access
```

If you get a warning that says, "entry rules deprecated, changing to exit rule". This means that you have a rule intended for the entry filter, but that filter is no longer available. Auditctl moved your rule to the exit filter so that it's not lost. But to solve this so that you do not get the warning any more, you need to change the offending rule from entry to exit.

## EXAMPLES
The following rule shows how to audit failed access to files due to permission problems. Note that it takes two rules for each arch ABI to audit this since file access can fail with two different failure codes indicating permission problems.

```
-a always,exit -F arch=b32 -S open,openat,openat2 -F exit=-EACCES -k access
-a always,exit -F arch=b32 -S open,openat,openat2 -F exit=-EPERM -k access
-a always,exit -F arch=b64 -S open,openat,openat2 -F exit=-EACCES -k access
-a always,exit -F arch=b64 -S open,openat,openat2 -F exit=-EPERM -k access
```

## IO_URING RULES
Io_uring rules do not take an arch field. It is implicit in the specification of the filter. The following example rule watches for file opens through the io_uring subsystem:

```
-a always,io_uring -S openat,openat2 -F key=access
```

## HARD WIRED EVENTS
If auditing is enabled, then you can get any event that is not caused by syscall or file watch rules (because you don't have any rules loaded). So, that means, any event from 1100-1299, 1326, 1328, 1331 and higher can be emitted. The reason that there are a number of events that are hardwired is because they are required by regulatory compliance and are sent automatically as a convenience. (For example, logon/logoff is a mandatory event in all security guidance.) If you don't want this, you can use the exclude filter to drop events that you do not want.

```
-a always,exclude -F msgtype=CRED_REFR
```

## SEE ALSO
auditctl(8), auditd(8).

## AUTHOR
Steve Grubb


autopano-sift-c

package: autopano-sift-C

title: autopano-sift-c(7)

summary: Automatic panorama stitching package

text:
# autopano-sift-c(7)

## NAME
autopano-sift - Automatic panorama stitching package

## INTRODUCTION
The autopano-sift package contains a number programs to ease the creation of panoramic images. A tedious task in panoramic image creation from many individual images is the aligning of the images so they fit together. This is normally done by using control points which give information about shared image features. For example, image two images of a church. Lets assume both images overlap so that the rooftop of the church is visible in both. By telling a panorama software that the roof is in both images at a specific position the images can be aligned. At least three control point pairs between every two images are required usually.

The manual work of creating this control points can be immense. Especially for panorama images holding more than one line of images there is a huge number of possible overlaps.

The autopano-sift package can automatically create control point pairs by using a combination of sophisticated algorithms and models. For most feature-rich images it works very well, often outperforming humans in coverage, precision and speed.

In the following, the individual utilities are introduced. If you want a quick start, try the autopanog(1) GUI frontend.

## DESCRIPTION
autopanog The GTK# GUI frontend for generating and matching SIFT keypoints. As a user wanting to stitch panorama images, this is all you will ever need. See autopanog(1)

autopano The keypoint matching program. It can take SIFT keypoint files as input and produce PTO output files. See autopano(1)

generatekeys The SIFT keypoint extraction program. Takes an image from you, and gives keypoints back. Optionally can downscale the image to a given resolution, so your memory size is cared for. See generatekeys(1)

showone Show the SIFT keypoints overlayed over the source image. Use includes debugging and tuning of SIFT parameters and to get an impression how well spread the keypoints are. See showone(1)

showtwo Do simplistic matching of SIFT keypoints between two images, without geometric model. Use includes representing general matching quality. Optionally filter only a given number of "best" keypoint matches. See showtwo(1)

## BUGS
If you find any bugs in the programs, please mail the author.

## AUTHOR
Sebastian Nowozin <nowozin at cs dot tu dash berlin dot de>

## SEE ALSO
autopano(1), autopanog(1), generatekeys(1), showone(1), showtwo(1)


bats

package: bats

title: bats(7)

summary: Bats test file format

text:
# bats(7)

## NAME
bats - Bats test file format

## DESCRIPTION
A Bats test file is a Bash script with special syntax for defining test cases. Under the hood, each test case is just a function with a description.

```
#!/usr/bin/env bats
@test "addition using bc" {

  result="$(echo 2+2 | bc)"

  [ "$result" -eq 4 ]
}
@test "addition using dc" {

  result="$(echo 2 2+p | dc)"

  [ "$result" -eq 4 ]
}
```

Each Bats test file is evaluated n+1 times, where n is the number of test cases in the file. The first run counts the number of test cases, then iterates over the test cases and executes each one in its own process.

## Tagging tests
Each test has a list of tags attached to it. Without specification, this list is empty. Tags can be defined in two ways. The first being # bats test_tags=:

\# bats test_tags=tag:1, tag:2, tag:3 @test "second test" { # ... }

@test "second test" { # ... }

These tags (tag:1, tag:2, tag:3) will be attached to the test first test. The second test will have no tags attached. Values defined in the # bats test_tags= directive will be assigned to the next @test that is being encountered in the file and forgotten after that. Only the value of the last # bats test_tags= directive before a given test will be used.

Sometimes, we want to give all tests in a file a set of the same tags. This can be achieved via # bats file_tags=. They will be added to all tests in the file after that directive. An additional # bats file_tags= directive will override the previously defined values:

```
@test "Zeroth test" {

  # will have no tags
}
# bats file_tags=a:b
# bats test_tags=c:d
@test "First test" {

  # will be tagged a:b, c:d
}
# bats file_tags=
@test "Second test" {

  # will have no tags
}
```

Tags are case sensitive and must only consist of alphanumeric characters and _, -, or :. They must not contain whitespaces! The colon is intended as a separator for (recursive) namespacing.

Tag lists must be separated by commas and are allowed to contain whitespace. They must not contain empty tags like test_tags=,b (first tag is empty), test_tags=a,,c, test_tags=a, ,c (second tag is only whitespace/empty), test_tags=a,b, (third tag is empty).

Every tag starting with bats: (case insensitive!) is reserved for Bats´ internal use:

bats:focus

If any test with the tag bats:focus is encountered in a test suite, only those tagged with this tag will be executed. To prevent the CI from silently running on a subset of tests due to an accidentally committed bats:focus tag, the exit code of successful runs will be overridden to 1.

Should you require the true exit code, e.g. for a git bisect operation, you can disable this behavior by setting BATS_NO_FAIL_FOCUS_RUN=1 when running bats, but make sure to not commit this to CI!

## THE RUN HELPER
Usage: run [OPTIONS] [--]

Many Bats tests need to run a command and then make assertions about its exit status and output. Bats includes a run helper that invokes its arguments as a command, saves the exit status and output into special global variables, and (optionally) checks exit status against a given expected value. If successful, run returns with a 0 status code so you can continue to make assertions in your test case.

For example, let´s say you´re testing that the foo command, when passed a nonexistent filename, exits with a 1 status code and prints an error message.

```
@test "invoking foo with a nonexistent file prints an error" {

  run -1 foo nonexistent_filename

  [ "$output" = "foo: no such file ´nonexistent_filename´" ]
}
```

The -1 as first argument tells run to expect 1 as an exit status, and to fail if the command exits with any other value. On failure, both actual and expected values will be displayed, along with the invoked command and its output:

```
(in test file test.bats, line 2)

 `run -1 foo nonexistent_filename´ failed, expected exit code 1, got 127
```

This error indicates a possible problem with the installation or configuration of foo; note that a simple [ $status != 0 ] test would not have caught this kind of failure.

The $status variable contains the status code of the command, and the $output variable contains the combined contents of the command´s standard output and standard error streams.

A third special variable, the $lines array, is available for easily accessing individual lines of output. For example, if you want to test that invoking foo without any arguments prints usage information on the first line:

```
@test "invoking foo without arguments prints usage" {

  run -1 foo

  [ "${lines[0]}" = "usage: foo <filename>" ]
}
```

By default run leaves out empty lines in ${lines[@]}. Use run --keep-empty-lines to retain them.

Additionally, you can use --separate-stderr to split stdout and stderr into $output/$stderr and ${lines[@]}/${stderr_lines[@]}.

All additional parameters to run should come before the command. If you want to run a command that starts with -, prefix it with -- to prevent run from parsing it as an option.

## THE LOAD COMMAND
You may want to share common code across multiple test files. Bats includes a convenient load command for sourcing a Bash source file relative to the location of the current test file. For example, if you have a Bats test in test/foo.bats, the command

```
load test_helper
```

will source the script test/test_helper.bash in your test file. This can be useful for sharing functions to set up your environment or load fixtures.

## THE BATS_LOAD_LIBRARY COMMAND
Some libraries are installed on the system, e.g. by npm or brew. These should not be loaded, as their path depends on the installation method. Instead, one should use bats_load_library together with setting BATS_LIB_PATH, a PATH-like colon-delimited variable.

bats_load_library has two modes of resolving requests:

1.

by relative path from the BATS_LIB_PATH to a file in the library

2.

by library name, expecting libraries to have a load.bash entrypoint

For example if your BATS_LIB_PATH is set to ~/.bats/libs:/usr/lib/bats, then bats_load_library test_helper would look for existing files with the following paths:

○

~/.bats/libs/test_helper

○

~/.bats/libs/test_helper/load.bash

○

/usr/lib/bats/test_helper

○

/usr/lib/bats/test_helper/load.bash

The first existing file in this list will be sourced.

If you want to load only part of a library or the entry point is not named load.bash, you have to include it in the argument: bats_load_library library_name/file_to_load will try

○

~/.bats/libs/library_name/file_to_load

○

~/.bats/libs/library_name/file_to_load/load.bash

○

/usr/lib/bats/library_name/file_to_load

○

/usr/lib/bats/library_name/file_to_load/load.bash

Apart from the changed lookup rules, bats_load_library behaves like load.

Note: As seen above load.bash is the entry point for libraries and meant to load more files from its directory or other libraries.

Note: Obviously, the actual BATS_LIB_PATH is highly dependent on the environment. To maintain a uniform location across systems, (distribution) package maintainers are encouraged to use /usr/lib/bats/ as the install path for libraries where possible. However, if the package manager has another preferred location, like npm or brew, you should use this instead.

## THE SKIP COMMAND
Tests can be skipped by using the skip command at the point in a test you wish to skip.

```
@test "A test I don´t want to execute for now" {

  skip

  run -0 foo
}
```

Optionally, you may include a reason for skipping:

```
@test "A test I don´t want to execute for now" {

  skip "This command will return zero soon, but not now"

  run -0 foo
}
```

Or you can skip conditionally:

```
@test "A test which should run" {

  if [ foo != bar ]; then

    skip "foo isn´t bar"

  fi

  run -0 foo
}
```

## THE BATS_REQUIRE_MINIMUM_VERSION COMMAND
Code for newer versions of Bats can be incompatible with older versions. In the best case this will lead to an error message and a failed test suite. In the worst case, the tests will pass erroneously, potentially masking a failure.

Use bats_require_minimum_version <Bats version number> to avoid this. It communicates in a concise manner, that you intend the following code to be run under the given Bats version or higher.

Additionally, this function will communicate the current Bats version floor to subsequent code, allowing e.g. Bats´ internal warning to give more informed warnings.

Note: By default, calling bats_require_minimum_version with versions before Bats 1.7.0 will fail regardless of the required version as the function is not available. However, you can use the bats-backports plugin (https://github.com/bats-core/bats-backports) to make your code usable with older versions, e.g. during migration while your CI system is not yet upgraded.

## SETUP AND TEARDOWN FUNCTIONS
You can define special setup and teardown functions which run before and after each test case, respectively. Use these to load fixtures, set up your environment, and clean up when you´re done.

## CODE OUTSIDE OF TEST CASES
You can include code in your test file outside of @test functions. For example, this may be useful if you want to check for dependencies and fail immediately if they´re not present. However, any output that you print in code outside of @test, setup or teardown functions must be redirected to stderr (>&2). Otherwise, the output may cause Bats to fail by polluting the TAP stream on stdout.

## SPECIAL VARIABLES
There are several global variables you can use to introspect on Bats tests:

○

$BATS_TEST_FILENAME is the fully expanded path to the Bats test file.

○

$BATS_TEST_DIRNAME is the directory in which the Bats test file is located.

○

$BATS_TEST_NAMES is an array of function names for each test case.

○

$BATS_TEST_NAME is the name of the function containing the current test case.

○

BATS_TEST_NAME_PREFIX will be prepended to the description of each test on stdout and in reports.

○

$BATS_TEST_DESCRIPTION is the description of the current test case.

○

BATS_TEST_RETRIES is the maximum number of additional attempts that will be made on a failed test before it is finally considered failed. The default of 0 means the test must pass on the first attempt.

○

BATS_TEST_TIMEOUT is the number of seconds after which a test (including setup) will be aborted and marked as failed. Updates to this value in setup() or @test cannot change the running timeout countdown, so the latest useful update location is setup_file().

○

$BATS_TEST_NUMBER is the (1-based) index of the current test case in the test file.

○

$BATS_SUITE_TEST_NUMBER is the (1-based) index of the current test case in the test suite (over all files).

○

$BATS_TMPDIR is the base temporary directory used by bats to create its temporary files / directories. (default: $TMPDIR. If $TMPDIR is not set, /tmp is used.)

○

$BATS_RUN_TMPDIR is the location to the temporary directory used by bats to store all its internal temporary files during the tests. (default: $BATS_TMPDIR/bats-run-$BATS_ROOT_PID-XXXXXX)

○

$BATS_FILE_EXTENSION (default: bats) specifies the extension of test files that should be found when running a suite (via bats [-r] suite_folder/)

○

$BATS_SUITE_TMPDIR is a temporary directory common to all tests of a suite. Could be used to create files required by multiple tests.

○

$BATS_FILE_TMPDIR is a temporary directory common to all tests of a test file. Could be used to create files required by multiple tests in the same test file.

○

$BATS_TEST_TMPDIR is a temporary directory unique for each test. Could be used to create files required only for specific tests.

○

$BATS_VERSION is the version of Bats running the test.

## SEE ALSO
bash(1), bats(1)