icewm-programs

title: icewm-programs(5)

text:
# icewm-programs(5)

### NAME

```
 icewm-programs - icewm programs configuration file
```

### SYNOPSIS

```
 $ICEWM_PRIVCFG/programs
 $XDG_CONFIG_HOME/icewm/programs
 $HOME/.icewm/programs
 /etc/X11/icewm/programs
 /usr/share/X11/icewm/programs
```

### DESCRIPTION
The programs file is an automatically generated menu configuration file of installed programs. This file should be automatically generated by xdg_menu, wmconfig (Redhat), menu (Debian), or icewm-menu-fdo, perhaps as part of the login or X startup sequence.

### FORMAT
The format of the file contains one of the following line syntax:

prog ["]title["] icon program options

Specifies a program to execute when the menu item is selected.

restart ["]title["] icon program options

Specifies a program to replace the window manager when the menu item is selected. This is for launching other window managers from within icewm(1).

runonce ["]title["] icon "[res_name][.res_class]" program options

Specifies a program to execute when the menu item is selected; however, if a window of the specified res_name and res_class is present, the program will not be run again.

menu ["]title["] icon { # contained items }

Specifies a sub-menu. The lines that appear between the braces can be any menu item described here.

menufile ["]title["] icon ["]filename["]

Specifies a file from which to collect sub-menu items (lines) and place them at this point in the menu.

menuprog ["]title["] icon program options

Specifies a program that will print sub-menu items on standard output and will be collected and placed in the sub-menu at this point.

menuprogreload ["]title["] icon timeout program options

Similar to menuprog, but after at least timeout seconds the menu is regenerated.

include ["]filename["]

Read additional entries from the file filename

includeprog program options

Read additional entries from the output of program options.

separator

A separator for menu items.

Where

prog, restart, runonce, menu, menufile, menuprog, menuprogreload, include, includeprog, separator

These are literal string keywords.

["]title["]

This is the title string associated with the menu item that is displayed in the menu. When the title contains spaces, the title must be surrounded by double quotes ("""), although the title may always be surrounded by double quotes if preferred.

icon

Is the name of the icon file (with or without extension) or the full path to an icon file.

"[res_name][.res_class]"

res_name is the resource name of a window launched by program and res_class is the resource class of the window. Only one of res_name or res_class need be specified. This is used to identify whether the program is already running and is for use with the runonce keyword.

program options

program is the name of the executable or full path to the executable file that will be run in response to selecting the menu item. When used with the menuprog keyword, the program must print on standard output the contents of the menu and is used for dynamic menus. options is the options and arguments passed to the program verbatim.

filename

filename is the name of the file relative to one of the icewm(1) configuration directories, or the full path to a file. The file is used with the menufile keyword and specifies the file from which to read further menu items.

### EXAMPLES
Following is the example programs file that ships with icewm(1):

```
 # This file is intended to be customized by the distributions.
 # (they should place it in /etc/X11/icewm)
 #
 # mostly obsolete, fixme
 menu Editors folder {
     prog vim vim gvim
     prog emacs emacs emacs
     prog Lyx emacs lyx
 }
 menu "WWW" folder {
     prog Galeon galeon galeon
     prog Arena arena arena
     prog Lynx lynx xterm -e lynx
     prog Links lynx xterm -e links
 }
 menu "Document Viewers" folder {
     prog "DVI Previewer" xdvi xdvi
     prog "Ghostview" ghostview gv
 }
 menu Graphics folder {
     prog Gimp gimp gimp
     prog XV xv xv
     prog XPaint xpaint xpaint
     prog XFig xfig xfig
 }
 menu Games folder {
     prog Xboard xboard xboard
     prog "Tux Racer" tuxracer tuxracer
 }
 menu System folder {
     prog "Control Panel" redhat control-panel
 }
 menu Utilities folder {
     prog XPlayCD xplaycd xplaycd
     prog XMixer xmixer xmixer
     prog Clock xclock xclock
     prog Magnify xmag xmag
     prog Calculator xcalc xcalc
     prog Colormap xcolormap xcmap
     prog Clipboard xclipboard xclipboard
     prog xkill bomb xkill
     prog xload xload xload
     prog xosview xosview xosview
     separator
     prog "Screen Saver" xlock xlock -nolock
     prog "Screen Lock" xlock xlock
 }
 menu "Window Managers" folder {
     restart icewm - icewm
     restart metacity - metacity
     restart wmaker - wmaker
     restart fluxbox - fluxbox
     restart blackbox - blackbox
     restart enlightenment - enlightenment
     restart fvwm2 - fvwm2
     restart fvwm - fvwm
     restart sawfish - sawfish
     restart sawfish2 - sawfish2
 }
```

### FILES
Locations for the programs file are as follows:

```
 $ICEWM_PRIVCFG/programs
 $XDG_CONFIG_HOME/icewm/programs
 $HOME/.icewm/programs
 /etc/X11/icewm/programs
 /usr/share/X11/icewm/programs
```

The locations are searched in the order listed; the first file found is read and the remainder ignored.

### SEE ALSO
icewm(1), icewm-menu(5), icewm-menu-fdo(1).

### AUTHOR
Brian Bidulock <mailto:bidulock@openss7.org>.

### LICENSE
IceWM is licensed under the GNU Library General Public License. See the COPYING file in the distribution.


icewm-shutdown

package: icewm

title: icewm-shutdown(5)

text:
# icewm-shutdown(5)

### NAME

```
 icewm-shutdown - icewm shutdown configuration file
```

### SYNOPSIS

```
 $ICEWM_PRIVCFG/shutdown
 $XDG_CONFIG_HOME/icewm/shutdown
 $HOME/.icewm/shutdown
 /etc/X11/icewm/shutdown
 /usr/share/X11/icewm/shutdown
```

### DESCRIPTION
Contains commands to be executed on icewm shutdown. This is an executable script with commands to be executed in the last stage of icewm termination. Typically they may undo some of the effects of the startup script. It is run by icewm-session(1) when icewm terminates.

### FILES
Locations for the shutdown file are as follows:

```
 $ICEWM_PRIVCFG/shutdown
 $XDG_CONFIG_HOME/icewm/shutdown
 $HOME/.icewm/shutdown
 /etc/X11/icewm/shutdown
 /usr/share/X11/icewm/shutdown
```

The locations are searched in the order listed; the first file found is read and the remainder ignored.

### SEE ALSO
icewm-session(1), icewm-startup(5).

### AUTHOR
Brian Bidulock <mailto:bidulock@openss7.org>.

### LICENSE
IceWM is licensed under the GNU Library General Public License. See the COPYING file in the distribution.


icewm-startup

title: icewm-startup(5)

text:
# icewm-startup(5)

### NAME

```
 icewm-startup - icewm startup configuration file
```

### SYNOPSIS

```
 $ICEWM_PRIVCFG/startup
 $XDG_CONFIG_HOME/icewm/startup
 $HOME/.icewm/startup
 /etc/X11/icewm/startup
 /usr/share/X11/icewm/startup
```

### DESCRIPTION
The startup file contains commands to be executed on icewm startup. This is an executable script. Typically the commands tweak X11 settings and launch some applications that always need to be active. It is run by icewm-session(1) when icewm starts.

### EXAMPLES

```
 #!/bin/bash
 xset r rate 250 32
 flameshot &
 volumeicon &
 redshift-gtk &
 picom -b
```

Remember to "chmod +x ~/.icewm/startup". The first line must be a hash-bang, followed by the path of your script interpreter or shell.

### FILES
Locations for the startup file are as follows:

```
 $ICEWM_PRIVCFG/startup
 $XDG_CONFIG_HOME/icewm/startup
 $HOME/.icewm/startup
 /etc/X11/icewm/startup
 /usr/share/X11/icewm/startup
```

The locations are searched in the order listed; the first file found is executed and the remainder ignored.

### SEE ALSO
icewm-session(1), icewm-shutdown(5).

### AUTHOR
Brian Bidulock <mailto:bidulock@openss7.org>.

### LICENSE
IceWM is licensed under the GNU Library General Public License. See the COPYING file in the distribution.


icewm-theme

title: icewm-theme(5)

text:
# icewm-theme(5)

### NAME

```
 icewm-theme - icewm theme configuration file
```

### SYNOPSIS

```
 $ICEWM_PRIVCFG/theme
 $XDG_CONFIG_HOME/icewm/theme
 $HOME/.icewm/theme
 /etc/X11/icewm/theme
 /usr/share/X11/icewm/theme
```

### DESCRIPTION
The theme file contains the name of the default theme. On startup icewm reads this file to obtain the theme name, unless icewm was started with the --theme option. Whenever a different theme is selected from the icewm Menu then the theme file is overwritten with the name of the selected theme.

### FORMAT
This theme file contains the keyword "Theme", followed by an equals sign, followed by a double-quoted string with the theme name. The theme name is the name of the theme directory, followed by a slash, followed by the theme file.

Usually the theme file is just default.theme, but a theme may have alternatives. Alternatives are small tweaks of a theme. These are specified in their own .theme file, which replaces default.theme.

If no theme file exists then icewm will use the default setting of "Theme="icedesert/default.theme"".

### EXAMPLES
Following is a theme file. The comments show that icewm(1) keeps a history of previous theme settings.

```
    Theme="CrystalBlue/default.theme"
    #Theme="icedesert/default.theme"
    ##Theme="default/default.theme"
```

### FILES
Locations for the theme file are as follows:

```
 $ICEWM_PRIVCFG/theme
 $XDG_CONFIG_HOME/icewm/theme
 $HOME/.icewm/theme
 /etc/X11/icewm/theme
 /usr/share/X11/icewm/theme
```

The locations are searched in the order listed; the first file found is read and the remainder ignored.

### SEE ALSO
icewm(1), icewm-preferences(5), icewm-prefoverride(5).

### AUTHOR
Brian Bidulock <mailto:bidulock@openss7.org>.

### LICENSE
IceWM is licensed under the GNU Library General Public License. See the COPYING file in the distribution.


icewm-toolbar

title: icewm-toolbar(5)

text:
# icewm-toolbar(5)

### NAME

```
 icewm-toolbar - icewm toolbar configuration file
```

### SYNOPSIS

```
 $ICEWM_PRIVCFG/toolbar
 $XDG_CONFIG_HOME/icewm/toolbar
 $HOME/.icewm/toolbar
 /etc/X11/icewm/toolbar
 /usr/share/X11/icewm/toolbar
```

### DESCRIPTION
The toolbar file is responsible for configuring quick launch application icons that are placed on the icewm(1) panel. It contains names of quick to launch applications with icons for the task bar. Each non-empty non-comment line starts with the keyword prog. After one or more spaces follows a name, which is displayed in a tool tip whenever the mouse cursor hovers over the toolbar icon. This name may be a double quoted string. Then follows the bare name of the icon to use without extensions. This icon will be shown in the toolbar. The last component is a shell command line that will be executed whenever the user presses the icon in the toolbar. For example, the following line in toolbar will create a button with tool tip "Mozilla Firefox" with the firefox icon which launches firefox(1) when clicked:

```
    prog  "Mozilla Firefox"  firefox  /usr/bin/firefox --private-window
```

### FORMAT
The format of the file contains one of the following line syntax:

prog "title" icon program options

Where,

prog

The literal string prog.

"title"

The title of the toolbar item, which will appear as a tool-tip for the program button, enclosed in double quotes (""").

icon

The icon to display on the toolbar button. May be specified as a single dash ("-") when no icon is provided. When no icon is provided, the title text will be displayed on the button in place of the icon.

program

The executable program (full path or executable name) to run when the button is pressed.

options

Options and arguments that are passed to program.

Lines beginning with a hash ("#") are comment lines. Comment lines and blank lines are ignored.

### EXAMPLES
Following is an example that places a number of toolbar buttons on the icewm(1) panel:

```
    prog "File Manager" file-manager.png pcmanfm
    prog "Web Browser" web-browser.png /usr/lib/firefox/firefox
    prog "Terminal" terminal.png roxterm
    prog "Graphical Editor" text-editor.png gvim -f
    prog "Calculator" accessories-calculator.png calculator
    prog "Run Command" gtk-execute.png xde-run
    prog "Network" gtk-network.png pcmanfm ~/Network
    prog "Logout" system-log-out.png xde-logout
```

### FILES
Locations for the toolbar file are as follows:

```
 $ICEWM_PRIVCFG/toolbar
 $XDG_CONFIG_HOME/icewm/toolbar
 $HOME/.icewm/toolbar
 /etc/X11/icewm/toolbar
 /usr/share/X11/icewm/toolbar
```

The locations are searched in the order listed; the first file found is read and the remainder ignored.

### SEE ALSO
icewm(1), icewm-programs(5), icewm-menu(5), icewm-menu-fdo(1).

### AUTHOR
Brian Bidulock <mailto:bidulock@openss7.org>.

### LICENSE
IceWM is licensed under the GNU Library General Public License. See the COPYING file in the distribution.


icewm-winoptions

title: icewm-winoptions(5)

text:
# icewm-winoptions(5)

### NAME

```
 icewm-winoptions - IceWM window options configuration file
```

### SYNOPSIS

```
 $ICEWM_PRIVCFG/winoptions
 $XDG_CONFIG_HOME/icewm/winoptions
 $HOME/.icewm/winoptions
 /etc/X11/icewm/winoptions
 /usr/share/X11/icewm/winoptions
```

### DESCRIPTION
The IceWM winoptions file contains settings to control application specific window appearance and behavior. For instance, they control the window border, placement and size, the window layer, its workspace, its visibility on the task bar and its focus behavior.

The winoptions are established when icewm(1) starts. However, they can be overridden later using icesh(1) or icewmhint(1). The command "icesh winoptions" instructs icewm to reload the winoptions file, while icewmhint tunes a specific application instance when it starts.

### FORMAT
Each line in the file must be in one of the following formats:

NAME.CLASS.OPTION: VALUE

CLASS.ROLE.OPTION: VALUE

NAME.ROLE.OPTION: VALUE

CLASS.OPTION: VALUE

NAME.OPTION: VALUE

ROLE.OPTION: VALUE

.OPTION: VALUE

Here NAME and CLASS are from the WM_CLASS property of the window. This can be found in the output of "icesh -a getClass".

While ROLE refers to the WM_WINDOW_ROLE property of the window, which is the application instance specific name. Only a minority of windows have it. See the output of "icesh -a list prop WM_WINDOW_ROLE".

In rare cases, a name, class or role may contain a period. If it does, the period should be escaped by a single backslash.

Lastly, the OPTION: VALUE pair refer to the options and values described below. A line with just a dot, followed by an option/value pair, applies to all windows.

### OPTIONS
There are four categories: general, function, decor and feature.

### GENERAL OPTIONS
These control general characteristics of windows:

icon: NAME (default: none)

Specifies the icon name for the window. NAME is the icon name, like utilities-terminal. It can also be a file, like xterm.png, a full path, or a prefix of a path without sizes or suffix.

workspace: WORKSPACE (default: current)

Specifies the default workspace for the window. WORKSPACE is the workspace number counting from zero (0).

layer: {LAYER|NUMBER} (default: Normal)

Specifies the default layer for the window. Layer can be one of the following names or a number from zero to fifteen:

```
  Desktop     (0)  Desktop window.
  Below       (2)  Below the default layer.
  Normal      (4)  Default layer for windows.
  OnTop       (6)  Above the default layer.
  Dock        (8)  Docked windows at edge of screen.
  AboveDock  (10)  Windows above the dock.
  Menu       (12)  The layer for menu's.
  Fullscreen (14)  When fullscreen and focused.
  AboveAll   (15)  Always above anything.

```

geometry geometry (default: WM_SIZE_HINTS property)

The default geometry for the window. This geometry should be specified in a format that can be parsed by XParseGeometry(3):

```
 [=][<width>{xX}<height>][{+-}<xoffset>{+-}<yoffset>]

```

The default geometry is taken from the WM_SIZE_HINTS property of the window or else from the initial window geometry. This option overrides the default.

tray: {Ignore|Minimized|Exclusive|NUMBER} (default: 0)

The default tray option for the window. This affects both the tray and the task pane. Tray can be one of the following three strings or a number from zero (0) to two (2):

```
  Ignore     (0)  No icon is added to the tray.
  Minimized  (1)  Add to tray, no task when minimized.
  Exclusive  (2)  Add to tray, no task button.

```

order: NUMBER (default: 0)

The sorting order for task buttons, tray icons, quick switch and window list. The default value is zero. Increasing positive values go right, while decreasing negative values go left.

opacity: NUMBER (default: 0)

Set the _NET_WM_WINDOW_OPACITY property if NUMBER is a value between 1 and 100. NUMBER is interpreted as percentage of maximum opaqueness.

keyboard: layout (default: none)

Specifies the keyboard layout to use for this window. The layout is the name of a keyboard layout. It can be a space-separated list of arguments to the setxkbmap program. Please note that setxkbmap must be installed for this to work. Also define a default keyboard layout in preferences.

frame: label (default: none)

All windows with the same frame label become tabs in a single frame.

### FUNCTION OPTIONS
Function options enable/disable (1/0) the ability to take an action on the window. The normal default for all options is enabled (1) unless overridden by the application:

```
  fClose:    {0|1}  can be closed.        (default: 1)
  fHide:     {0|1}  can be hidden.        (default: 1)
  fMaximize: {0|1}  can be maximized.     (default: 1)
  fMinimize: {0|1}  can be minimized.     (default: 1)
  fMove:     {0|1}  can be moved.         (default: 1)
  fResize:   {0|1}  can be resized.       (default: 1)
  fRollup:   {0|1}  can be shaded.        (default: 1)
```

### DECOR OPTIONS
Decor options enable/disable (1/0) decorations on the window. The normal default for all options is enabled (1) unless overridden by the application or the theme:

```
  dBorder:   {0|1}  has border.           (default: 1)
  dClose:    {0|1}  has close button.     (default: 1)
  dDepth:    {0|1}  has depth button.     (default: 1)
  dHide:     {0|1}  has hide button.      (default: 1)
  dMaximize: {0|1}  has maximize button.  (default: 1)
  dMinimize: {0|1}  has minimize button.  (default: 1)
  dResize:   {0|1}  has resize grips.     (default: 1)
  dRollup:   {0|1}  has shade button.     (default: 1)
  dSysMenu:  {0|1}  has window menu.      (default: 1)
  dTitleBar: {0|1}  has title bar.        (default: 1)
```

### FEATURE OPTIONS
Feature options enable/disable (1/0) additional features of the window. The normal default for all options is disabled (0) unless overridden by the application:

```
  allWorkspaces:            {1|0}  on all workspaces.
  appTakesFocus:            {1|0}  let application take focus.
  doNotCover:               {1|0}  limits workspace if sticky.
  doNotFocus:               {1|0}  do not focus.
  doNotManage:              {1|0}  do not manage.
  forcedClose:              {1|0}  no close confirmation dialog.
  fullKeys:                 {1|0}  don't install icewm key bindings.
  ignoreNoFocusHint:        {1|0}  focus even when no-input is set.
  ignorePagerPreview:       {1|0}  do not show in pager preview.
  ignorePositionHint:       {1|0}  always let icewm place the window.
  ignoreQuickSwitch:        {1|0}  not on quick switch.
  ignoreTaskBar:            {1|0}  not on task bar.
  ignoreUrgentHint:         {1|0}  ignore urgent hints.
  ignoreWinList:            {1|0}  not on window list.
  ignoreActivationMessages: {1|0}  only user can focus window.
  ignoreOverrideRedirect:   {1|0}  ignore the override redirect flag.
  noFocusOnAppRaise:        {1|0}  no automatic focus on raise.
  noFocusOnMap:             {1|0}  do not focus when mapped.
  noIgnoreTaskBar:          {1|0}  always show on task bar.
  startClose:               {1|0}  close the window immediately.
  startFullscreen:          {1|0}  start full screen.
  startMaximized:           {1|0}  start maximized.
  startMaximizedHorz:       {1|0}  start maximized horizontal.
  startMaximizedVert:       {1|0}  start maximized vertical.
  startMinimized:           {1|0}  start minimized.
```

### EXAMPLES
This example uses the WM_WINDOW_ROLE property value "pop-up" to deny input focus to Chrome pop-ups and asks to close them immediately.

```
  google-chrome.pop-up.doNotFocus: 1
  google-chrome.pop-up.forcedClose: 1
  google-chrome.pop-up.ignorePagerPreview: 1
  google-chrome.pop-up.ignoreUrgentHint: 1
  google-chrome.pop-up.layer: Below
  google-chrome.pop-up.noFocusOnAppRaise: 1
  google-chrome.pop-up.noFocusOnMap: 1
  google-chrome.pop-up.startClose: 1
  google-chrome.pop-up.startMinimized: 1
```

IceWM places dockapps in a container automatically, but for those that fail to comply with the protocol it can also be emulated. An emulated dockapp should appear on all workspaces, have no decorations, and always be visible in a fixed location.

```
  wmtime.wmtime.allWorkspaces: 1
  wmtime.wmtime.ignoreTaskBar: 1
  wmtime.wmtime.ignoreQuickSwitch: 1
  wmtime.wmtime.ignoreWinList: 1
  wmtime.wmtime.layer: Below
  wmtime.wmtime.dTitleBar: 0
  wmtime.wmtime.dBorder: 1
  wmtime.wmtime.geometry: 64x64-74-100
```

Following shows how a shaped output-only application is shown without titlebar and minimal functionality.

```
  xeyes.tray: Exclusive
  xeyes.ignoreWinList: 0
  xeyes.ignoreTaskBar: 1
  xeyes.allWorkspaces: 1
  xeyes.dTitleBar: 0
  xeyes.dBorder: 0
  xeyes.dSysMenu: 0
  xeyes.dResize: 0
  xeyes.dClose: 0
  xeyes.dMinimize: 0
  xeyes.dMaximize: 0
```

### FILES
Locations for the winoptions file are as follows:

```
 $ICEWM_PRIVCFG/winoptions
 $XDG_CONFIG_HOME/icewm/winoptions
 $HOME/.icewm/winoptions
 /etc/X11/icewm/winoptions
 /usr/share/X11/icewm/winoptions
```

The locations are searched in the order listed; the first file found is read and the remainder ignored.

### SEE ALSO
icewm(1), icesh(1), icewmhint(1), setxkbmap(1), XParseGeometry(3).

### AUTHOR
Brian Bidulock <mailto:bidulock@openss7.org>.

### LICENSE
IceWM is licensed under the GNU Library General Public License. See the COPYING file in the distribution.


ifplugd.conf

package: ifplugd

title: ifplugd.conf(5)

summary: ifplugd configuration file

text:
# ifplugd.conf(5)

## NAME
ifplugd.conf - ifplugd configuration file

## SYNOPSIS
/etc/ifplugd/ifplugd.conf

## DESCRIPTION
ifplugd.conf is the configuration file for ifplugd. It is a shell script that is sourced by the init script starting the daemon. It shall be used to set environment variables which are interpreted by the init script:

## OPTIONS
INTERFACES

Specifies the ethernet interfaces to monitor. It has to contain a space seperated list of network interfaces names. Most users will probably use "eth0" here, however you may add additional interfaces for monitoring more than one device. A special value is supported as well: "auto" will enable a more or less working auto detection of available network devices. This won't make you happy when using network module auto loading, since it cannot detect currently unloaded network devices.

ARGS

Additional command line arguments for ifplugd invocation. See ifplugd(8) for further information.

ARGS_iface

If specified for an interface this variable takes precedence over ARGS. This may be useful if more than one network device is present.

## SEE ALSO
ifplugd(8)

## COMMENTS
This man page was written using xmltoman(1) by Oliver Kurth.


iftab

package: ifrename

title: iftab(5)

text:
# iftab(5)

## NAME
iftab - static information about the network interfaces

## DESCRIPTION
The file /etc/iftab contains descriptive information about the various network interfaces. iftab is only used by the program ifrename(8) to assign a consistent network interface name to each network interface.

/etc/iftab defines a set of mappings. Each mapping contains an interface name and a set of selectors. The selectors allow ifrename to identify each network interface on the system. If a network interface matches all descriptors of a mapping, ifrename attempt to change the name of the interface to the interface name given by the mapping.

## MAPPINGS
Each mapping is described on a separate line, it starts with an interface name, and contains a set of descriptors, separated by space or tabs.

The relationship between descriptors of a mapping is a logical and. A mapping matches a network interface only is all the descriptors match. If a network interface doesn't support a specific descriptor, it won't match any mappings using this descriptor.

If you want to use alternate descriptors for an interface name (logical or), specify two different mappings with the same interface name (one on each line). Ifrename always use the first matching mapping starting from the end of iftab, therefore more restrictive mapping should be specified last.

## INTERFACE NAME
The first part of each mapping is an interface name. If a network interface matches all descriptors of a mapping, ifrename attempt to change the name of the interface to the interface name given by the mapping.

The interface name of a mapping is either a plain interface name (such as eth2 or wlan1) or a interface name pattern containing a single wildcard (such as eth* or wlan*). In case of wildcard, the kernel replace the '*' with the lowest available integer making this interface name unique. Note that wildcard is only supported for kernel 2.6.1 and 2.4.30 and later.

It is discouraged to try to map interfaces to default interfaces names such as eth0, wlan0 or ppp0. The kernel use those as the default name for any new interface, therefore most likely an interface will already use this name and prevent ifrename to use it. Even if you use takeover, the interface may already be up in some cases. Not using those name will allow you to immediately spot unconfigured or new interfaces.

Good names are either totally unique and meaningfull, such as mydsl or privatehub, or use larger integer, such as eth5 or wlan5. The second type is usually easier to integrate in various network utilities.

## DESCRIPTORS
Each descriptor is composed of a descriptor name and descriptor value. Descriptors specify a static attribute of a network interface, the goal is to uniquely identify each piece of hardware.

Most users will only use the mac selector despite its potential problems, other selectors are for more specialised setup. Most selectors accept a '*' in the selector value for wilcard matching, and most selectors are case insensitive.

mac mac address

Matches the MAC Address of the interface with the specified MAC address. The MAC address of the interface can be shown using ifconfig(8) or ip(8).

This is the most common selector, as most interfaces have a unique MAC address allowing to identify network interfaces without ambiguity. However, some interfaces don't have a valid MAC address until they are brought up, in such case using this selector is tricky or impossible.

arp arp type

Matches the ARP Type (also called Link Type) of the interface with the specified ARP type as a number. The ARP Type of the interface can be shown using ifconfig(8) or ip(8), the link/ether type correspond to 1 and the link/ieee802.11 type correspond to 801.

This selector is useful when a driver create multiple network interfaces for a single network card.

driver driver name

Matches the Driver Name of the interface with the specified driver name. The Driver Name of the interface can be shown using ethtool -i(8).

businfo bus information

Matches the Bus Information of the interface with the specified bus information. The Bus Information of the interface can be shown using ethtool -i(8).

firmware firmware revision

Matches the Firmware Revision of the interface with the firmware revision information. The Firmware Revision of the interface can be shown using ethtool -i(8).

baseaddress base address

Matches the Base Address of the interface with the specified base address. The Base Address of the interface can be shown using ifconfig(8).

Because most cards use dynamic allocation of the Base Address, this selector is only useful for ISA and EISA cards.

irq irq line

Matches the IRQ Line (interrupt) of the interface with the specified IRQ line. The IRQ Line of the interface can be shown using ifconfig(8).

Because there are IRQ Lines may be shared, this selector is usually not sufficient to uniquely identify an interface.

iwproto wireless protocol

Matches the Wireless Protocol of the interface with the specified wireless protocol. The Wireless Protocol of the interface can be shown using iwconfig(8) or iwgetid(8).

This selector is only supported on wireless interfaces and is not sufficient to uniquely identify an interface.

pcmciaslot pcmcia slot

Matches the Pcmcia Socket number of the interface with the specified slot number. Pcmcia Socket number of the interface can be shown using cardctl ident(8).

This selector is usually only supported on 16 bits cards, for 32 bits cards it is advised to use the selector businfo.

prevname previous interface name

Matches the name of the interface prior to renaming with the specified oldname.

This selector should be avoided as the previous interface name may vary depending on various condition. A system/kernel/driver update may change the original name. Then, ifrename or another tool may rename it prior to the execution of this selector.

SYSFS{filename} value

Matches the content the sysfs attribute given by filename to the specified value. For symlinks and parents directories, match the actual directory name of the sysfs attribute given by filename to the specified value.

A list of the most useful sysfs attributes is given in the next section.

## SYSFS DESCRIPTORS
Sysfs attributes for a specific interface are located on most systems in the directory named after that interface at /sys/class/net/. Most sysfs attribute are files, and their values can be read using cat(1) or more(1). It is also possible to match attributes in subdirectories.

Some sysfs attributes are symlinks, pointing to another directory in sysfs. If the attribute filename is a symlink the sysfs attribute resolves to the name of the directory pointed by the symlink using readlink(1). The location is a directory in the sysfs tree is also important. If the attribute filename ends with /.., the sysfs attribute resolves to the real name of the parent directory using pwd(1).

The sysfs filesystem is only supported with 2.6.X kernel and need to be mounted (usually in /sys). sysfs selectors are not as efficient as other selectors, therefore they should be avoided for maximum performance.

These are common sysfs attributes and their corresponding ifrename descriptors.

SYSFS{address} value

Same as the mac descriptor.

SYSFS{type} value

Same as the arp descriptor.

SYSFS{device} value

Valid only up to kernel 2.6.20. Same as the businfo descriptor.

SYSFS{..} value

Valid only from kernel 2.6.21. Same as the businfo descriptor.

SYSFS{device/driver} value

Valid only up to kernel 2.6.20. Same as the driver descriptor.

SYSFS{../driver} value

Valid only from kernel 2.6.21. Same as the driver descriptor.

SYSFS{device/irq} value

Valid only up to kernel 2.6.20. Same as the irq descriptor.

SYSFS{../irq} value

Valid only from kernel 2.6.21. Same as the irq descriptor.

## EXAMPLES
\# This is a comment

eth2 mac 08:00:09:DE:82:0E

eth3 driver wavelan interrupt 15 baseaddress 0x390

eth4 driver pcnet32 businfo 0000:02:05.0

air* mac 00:07:0E:* arp 1

myvpn SYSFS{address} 00:10:83:* SYSFS{type} 1

bcm* SYSFS{device} 0000:03:00.0 SYSFS{device/driver} bcm43xx

bcm* SYSFS{..} 0000:03:00.0 SYSFS{../driver} bcm43xx

## AUTHOR
Jean Tourrilhes - jt@hpl.hp.com

## FILES
/etc/iftab

## SEE ALSO
ifrename(8), ifconfig(8), ip(8), ethtool(8), iwconfig(8).


ifupdown-addons-interfaces

title: ifupdown-addons-interfaces(5)

text:
# ifupdown-addons-interfaces(5)

## NAME
ifupdown-addons-interfaces - ifupdown2 addon modules interface configuration

## DESCRIPTION
ifupdown2 addon modules add incremental functionality to core ifupdown2 tool. All installed addon modules are executed on every interface listed in the interfaces file. Addon modules are installed under /usr/share/ifupdownaddons. To see the list of active addon modules, see ifaddon(8).

Addon modules add new attributes to the interfaces(5) file. Below is a list of attribute options provided by each module. These can be listed under each iface section in the interfaces(5) file.

## EXAMPLES
Listed below are addon modules and their supported attributes. The attributes if applicable go under the iface section in the interfaces(5) file. ethtool: ethtool configuration module for interfaces

link-duplex help: set link duplex required: False

default: half

validvals: half,full

example:

link-duplex full

link-autoneg

help: set autonegotiation required: False

default: no

validvals: yes,no

example:

link-autoneg yes

link-speed

help: set link speed required: False

example:

link-speed 1000

bridge: Bridge configuration module. Supports both vlan aware and non vlan aware bridges. For the vlan aware bridge, the port sp ecific attributes must be specified under the port. And for vlan u naware bridge port specific attributes must be specified under the bridge.

bridge-vlan-aware help: vlan aware bridge. Setting this attribute to yes ena bles vlan filtering on the bridge required: False

example:

bridge-vlan-aware yes/no

bridge-pathcosts

help: bridge set port path costs required: False

default: 100

example:

bridge-pathcosts swp1=100 swp2=100

bridge-portprios

help: bridge port prios required: False

default: 32

example:

bridge-portprios swp1=32 swp2=32

bridge-fd

help: bridge forward delay required: False

default: 15

example:

bridge-fd 15

bridge-ageing

help: bridge ageing required: False

default: 300

example:

bridge-ageing 300

bridge-hello

help: bridge set hello time required: False

default: 2

example:

bridge-hello 2

bridge-gcint

help: bridge garbage collection interval in secs required: False

default: 4

example:

bridge-gcint 4

bridge-mcquerier

help: set multicast querier required: False

default: no

validvals: yes,no

example:

bridge-mcquerier no

bridge-mclmc

help: set multicast last member count required: False

default: 2

example:

bridge-mclmc 2

bridge-mcsqc

help: set multicast startup query count required: False

default: 2

example:

bridge-mcsqc 2

bridge-mcrouter

help: set multicast router required: False

default: yes

validvals: yes,no

example:

bridge-mcrouter yes

bridge-stp

help: bridge-stp yes/no required: False

default: no

validvals: yes,on,off,no

example:

bridge-stp no

bridge-pvid

help: bridge port pvid. Must be specified under the bridge port required: False

example:

bridge-pvid 1

bridge-mcsqi

help: set multicast startup query interval (in secs) required: False

default: 31

example:

bridge-mcsqi 31

bridge-mcmi

help: set multicast membership interval (in secs) required: False

default: 260

example:

bridge-mcmi 260

bridge-mclmi

help: set multicast last member interval (in secs) required: False

default: 1

example:

bridge-mclmi 1

bridge-vids

help: bridge port vids. Can be specified under the bridge or under the port. If specified under the bridge the ports inh erit it unless overridden by a bridge-vids attribuet under the port required: False

example:

bridge-vids 4000 bridge-vids 2000 2200-3000

bridge-ports

help: bridge ports required: True

example:

bridge-ports swp1.100 swp2.100 swp3.100 bridge-ports glob swp1-3.100

bridge-ports glob swp[1-3]s[0-4].100

bridge-ports regex (swp[1|2|3].100)

bridge-mcqifaddr

help: set multicast query to use ifaddr required: False

default: no

validvals: yes,no

example:

bridge-mcqifaddr no

bridge-waitport

help: wait for a max of time secs for the specified ports to become available,if no ports are specified then those speci fied on bridge-ports will be used here. Specifying no ports he re should not be used if we are using regex or "all" on bridge _ports,as it wouldnt work. required: False

default: 0

example:

bridge-waitport 4 swp1 swp2

bridge-mcqri

help: set multicast query response interval (in secs) required: False

default: 10

example:

bridge-mcqri 10

bridge-hashel

help: set hash elasticity required: False

default: 4096

example:

bridge-hashel 4096

bridge-mcqpi

help: set multicast querier interval (in secs) required: False

default: 255

example:

bridge-mcqpi 255

bridge-hashmax

help: set hash max required: False

default: 4096

example:

bridge-hashmax 4096

bridge-bridgeprio

help: bridge priority required: False

default: 32768

example:

bridge-bridgeprio 32768

bridge-maxage

help: bridge set maxage required: False

default: 20

example:

bridge-maxage 20

bridge-mcsnoop

help: set multicast snooping required: False

default: yes

validvals: yes,no

example:

bridge-mcsnoop yes

bridge-access

help: bridge port access vlan. Must be specified under the bridge port required: False

example:

bridge-access 300

bridge-maxwait

help: forces to time seconds the maximum time that the Deb ian bridge setup scripts will wait for the bridge ports to ge t to the forwarding status, doesn't allow factional part. If i t is equal to 0 then no waiting is done required: False

default: 0

example:

bridge-maxwait 3

bridge-portmcrouter

help: set port multicast routers required: False

default: 1

example:

under the bridge: bridge-portmcrouter swp1=1 swp2=1 under the port: bridge-portmcrouter 1

bridge-portmcfl

help: port multicast fast leave. required: False

default: 0

example:

under the bridge: bridge-portmcfl swp1=0 swp2=0 under the port: bridge-portmcfl 0

bridge-mcqi

help: set multicast query interval (in secs) required: False

default: 125

example:

bridge-mcqi 125

usercmds: user commands for interfaces

down help: run command at interface down required: False

post-up

help: run command after interface bring up required: False

up

help: run command at interface bring up required: False

pre-down

help: run command before bringing the interface down required: False

pre-up

help: run command before bringing the interface up required: False

post-down

help: run command after bringing interface down required: False

mstpctl: mstp configuration module for bridges

mstpctl-portadminedge help: enable/disable initial edge state of the port required: False

default: no

validvals: yes,no

example:

mstpctl-portadminedge swp1=no swp2=no

mstpctl-portbpdufilter

help: enable/disable bpdu filter on a port. syntax varies when defined under a bridge vs under a port required: False

default: no

validvals: yes,no

example:

under a bridge: mstpctl-portbpdufilter swp1=no swp2=no under a port: mstpctl-portbpdufilter yes

mstpctl-fdelay

help: set forwarding delay required: False

default: 15

example:

mstpctl-fdelay 15

mstpctl-portnetwork

help: enable/disable bridge assurance capability for a por t required: False

default: no

validvals: yes,no

example:

mstpctl-portnetwork swp1=no swp2=no

mstpctl-txholdcount

help: bridge transmit holdcount required: False

default: 6

example:

mstpctl-txholdcount 6

mstpctl-forcevers

help: bridge force stp version required: False

default: rstp

example:

mstpctl-forcevers rstp

mstpctl-portautoedge

help: enable/disable auto transition to/from edge state of the port required: False

default: yes

validvals: yes,no

example:

mstpctl-portautoedge swp1=yes swp2=yes

mstpctl-maxhops

help: bridge max hops required: False

default: 15

example:

mstpctl-maxhops 15

mstpctl-treeprio

help: tree priority required: False

default: 32768

validrange: 0-65535

example:

mstpctl-treeprio 32768

mstpctl-treeportprio

help: port priority for MSTI instance required: False

default: 128

validrange: 0-240

example:

mstpctl-treeportprio swp1=128 swp2=128

mstpctl-portpathcost

help: bridge port path cost required: False

default: 0

example:

mstpctl-portpathcost swp1=0 swp2=1

mstpctl-portrestrtcn

help: enable/disable port ability to propagate received to pology change notification of the port required: False

default: no

validvals: yes,no

example:

mstpctl-portrestrtcn swp1=no swp2=no

mstpctl-maxage

help: max message age required: False

default: 20

example:

mstpctl-maxage 20

mstpctl-hello

help: set hello time required: False

default: 2

example:

mstpctl-hello 2

mstpctl-portrestrrole

help: enable/disable port ability to take root role of the port required: False

default: no

validvals: yes,no

example:

mstpctl-portrestrrole swp1=no swp2=no

mstpctl-bpduguard

help: enable/disable bpduguard required: False

default: no

validvals: yes,no

example:

mstpctl-bpduguard swp1=no swp2=no

mstpctl-ageing

help: ageing time required: False

default: 300

example:

mstpctl-ageing 300

mstpctl-treeportcost

help: port tree cost required: False

mstpctl-portp2p

help: bridge port p2p detection mode required: False

default: auto

validvals: yes,no,auto

example:

mstpctl-portp2p swp1=no swp2=no

clagd: This module generates the clagd defaults file.

clagd-priority help: The priority of this clagd switch required: False

example:

clagd-priority 30000

clagd-backup-ip

help: Backup IP address of the clagd peer required: False

example:

clagd-backup-ip 192.1.1.1

clagd-enable

help: enable clagd required: False

validvals: yes,no

example:

clagd-enable yes

clag-id

help: multi-chassis lag id required: False

default: 0

validrange: 0-65535

example:

clag-id 1

clagd-peer-ip

help: The IP address of the clagd peer required: True

example:

clagd-peer 10.10.10.2

clagd-sys-mac

help: The system ID of the CLAG pair required: True

example:

clagd-sys-mac 44:38:39:ff:00:00

clagd-args

help: Additional command line arguments for clagd required: False

example:

clagd-args --log /var/log/clagd.log clagd-args --verbose --lacpPoll 10

clagd-args --debug 0x4

vlan: vlan module configures vlan interfaces.This module under stands vlan interfaces with dot notations. eg swp1.100. Vlan inter faces with any other names need to have raw device and vlan id att ributes

vlan-id help: vlan id required: False

vlan-raw-device

help: vlan raw device required: False

bridgevlan: bridgevlan module configures vlan attributes on a vlan aware bridge. This module only understands vlan interface name with dot notations. eg br0.100. where br0 is the vlan aware bridge this config is for.

bridge-igmp-querier-src help: bridge igmp querier src. Must be specified under the vlan interface required: False

example:

bridge-igmp-querier-src 172.16.101.1

bond: bond configuration module

bond-use-carrier help: bond use carrier required: False

default: yes

validvals: yes,no

example:

bond-use-carrier yes

bond-lacp-bypass-period

help: grace period (seconds) for lacp bypass required: False

default: 0

validrange: 0-900

example:

bond-lacp-bypass-period 100

bond-miimon

help: bond miimon required: False

default: 0

validrange: 0-255

example:

bond-miimon 0

bond-lacp-rate

help: bond lacp rate required: False

default: 0

validvals: 0,1

example:

bond-lacp-rate 0

bond-lacp-bypass-priority

help: slave priority for lacp bypass required: False

example:

bond-lacp-bypass-priority swp1=1 swp2=1 swp3=2

bond-min-links

help: bond min links required: False

default: 0

example:

bond-min-links 0

bond-slaves

help: bond slaves required: True

example:

bond-slaves swp1 swp2 bond-slaves glob swp1-2

bond-slaves regex (swp[1|2)

bond-lacp-bypass-allow

help: allow lacp bypass required: False

default: no

validvals: yes,no

example:

bond-lacp-bypass-allow no

bond-mode

help: bond mode required: False

default: balance-rr

validvals: balance-rr,active-backup,balance-xor,broadcast,802.3ad,balance-tlb,balance-alb

example:

bond-mode 802.3ad

bond-num-unsol-na

help: bond slave devices required: False

default: 1

validrange: 0-255

example:

bond-num-unsol-na 1

bond-ad-sys-priority

help: 802.3ad system priority required: False

default: 65535

example:

bond-ad-sys-priority 65535

bond-xmit-hash-policy

help: bond slave devices required: False

default: layer2

validvals: layer2,layer3+4,layer2+3

example:

bond-xmit-hash-policy layer2

bond-num-grat-arp

help: bond use carrier required: False

default: 1

validrange: 0-255

example:

bond-num-grat-arp 1

bond-ad-sys-mac-addr

help: 802.3ad system mac address required: False

default: 00:00:00:00:00:00

example:

bond-ad-sys-mac-addr 00:00:00:00:00:00

address: address configuration module for interfaces

broadcast help: broadcast address required: False

example:

broadcast 10.0.1.255

hwaddress

help: hw address required: False

example:

hwaddress 44:38:39:00:27:b8

alias

help: description/alias required: False

example:

alias testnetwork

address

help: ipv4 or ipv6 addresses required: False

example:

address 10.0.12.3/24 address 2000:1000:1000:1000:3::5/128

scope

help: scope required: False

example:

scope host

address-purge

help: purge existing addresses. By default any existing ip addresses on an interface are purged to match persistent addre sses in the interfaces file. Set this attribute to 'no'if you want to preserve existing addresses required: False

default: yes

example:

address-purge yes/no

preferred-lifetime

help: preferred lifetime required: False

example:

preferred-lifetime forever preferred-lifetime 10

gateway

help: default gateway required: False

example:

gateway 255.255.255.0

mtu

help: interface mtu required: False

default: 1500

example:

mtu 1600

addressvirtual: address module configures virtual addresses fo r interfaces. It creates a macvlan interface for every mac ip addr ess-virtual line

address-virtual help: bridge router virtual mac and ip required: False

example:

address-virtual 00:11:22:33:44:01 11.0.1.254/24 11.0.1.254/24

vxlan: vxlan module configures vxlan interfaces.

vxlan-learning help: vxlan learning yes/no required: False

default: yes

validvals: yes,no

example:

vxlan-learning no

vxlan-id

help: vxlan id required: True

example:

vxlan-id 100

vxlan-remoteip

help: vxlan remote ip required: False

example:

vxlan-remoteip 172.16.22.127

vxlan-svcnodeip

help: vxlan id required: False

example:

vxlan-svcnodeip 172.16.22.125

vxlan-local-tunnelip

help: vxlan local tunnel ip required: False

example:

vxlan-local-tunnelip 172.16.20.103

## SEE ALSO
interfaces(5), ifup(8), ip(8), mstpctl(8), brctl(8), ethtool(8), clagctl(8)

## AUTHOR
roopa@cumulusnetworks.com

## COPYRIGHT
Copyright 2013 Cumulus Networks, Inc. All rights reserved.


interfaces

title: interfaces(5)

text:
# interfaces(5)

## NAME
interfaces - network interface configuration for ifupdown

## DESCRIPTION
By default, ifupdown2.conf sets /etc/network/interfaces as the network interface configuration file. This file contains information for the ifup(8), ifdown(8) and ifquery(8) commands. This is where you configure how your system is connected to the network.

Lines starting with # are ignored. Note that end-of-line comments are NOT supported, comments must be on a line of their own.

A line may be extended across multiple lines by making the last character a backslash.

The file consists of zero or more "iface", "auto", "allow-" and "source" stanzas. Here is an example:

```
auto lo eth0
allow-hotplug eth1
iface lo inet loopback
source /etc/network/interfaces.d/bridges
iface eth0 inet static

    address 192.168.1.1/24

    up flush-mail
iface eth1 inet dhcp
```

Lines beginning with the word "auto" are used to identify the physical interfaces to be brought up when ifup is run with the -a option. (This option is used by the system boot scripts.) Physical interface names should follow the word "auto" on the same line. There can be multiple "auto" stanzas.

Lines beginning with "allow-" are used to identify interfaces that should be brought up automatically by various subsystems. This may be done using a command such as "ifup --allow=hotplug eth0 eth1", which will only bring up eth0 or eth1 if it is listed in an "allow-hotplug" line. Note that "allow-auto" and "auto" are synonyms.

Lines beginning with "source" are used to include stanzas from other files, so configuration can be split into many files. The word "source" is followed by the path of the file to be sourced. Shell wildcards can be used. Currently only supports absolute path names.

iface is normally given a interface name as its first non-option argument.

The interface name is followed by the name of the address family that the interface uses. This will be "inet" for TCP/IP networking and inet6 for ipv6. Following that is the name of the method used to configure the interface.

ifupdown supports iface stanzas without a family or a method. This enables using the same stanza for inet and inet6 family addresses. And the method defaults to "static"

Additional interface options/attributes can be given on subsequent lines in the iface stanza. These options come from addon modules. see ifupdown-addons-interfaces(5) for these options.

example bridge interface with additional attributes listed in the ifupdown-addons-interfaces(5) man page:

```
auto br0
iface br0

    address 12.0.0.4/24

    address 2000:1000:1000:1000:3::5/128

    bridge-ports swp1 swp2 swp3

    bridge-stp on
```

ifupdown supports python-mako style templates in the interfaces file. See examples section for details.

See /usr/share/doc/ifupdown2/examples/ for interfaces(5) file examples and interfaces file generation scripts.

## METHODS
Both inet and inet6 address family interfaces can use the following methods (However they are not required): The loopback Method

This method may be used to define the loopback interface.

The static Method

This method may be used to define ethernet interfaces with statically allocated addresses.

The dhcp Method

This method may be used to obtain an address via DHCP.

inet6 address family interfaces can use the following method:

The auto Method

This method may be used to obtain an address via SLAAC.

## BUILTIN INTERFACES
iface sections for some interfaces like physical interfaces or vlan interfaces in dot notation (like eth1.100) are understood by ifupdown. These interfaces do not need an entry in the interfaces file if they are dependents of other interfaces and don't need any specific configurations like addresses etc.

## EXAMPLES
Sample /etc/network/interfaces file:

```
auto lo
iface lo

    address 192.168.2.0/24

    address 2001:dee:eeee:1::4/128
auto eth0
iface eth0 inet dhcp
auto eth1
iface eth1 inet manual

    address 192.168.2.0/24

    address 2001:dee:eeee:1::4/128
auto eth3
iface eth3 inet auto
# source files from a directory /etc/network/interfaces.d
source /etc/network/interfaces.d/*
# Using mako style templates
% for v in [11,12]:

    auto vlan${v}

    iface vlan${v} inet static

        address 10.20.${v}.3/24
% endfor
```

For additional syntax and examples see ifupdown-addons-interfaces(5)

## FILES
configuration file defined in ifupdown2.conf (default /etc/network/interfaces)

## SEE ALSO
ifupdown-addons-interfaces(5), ifup(8), ifquery(8), ifreload(8)

## AUTHOR
Roopa Prabhu <roopa@cumulusnetworks.com>

## COPYRIGHT
Copyright 2014 Cumulus Networks, Inc. All rights reserved.


igmpproxy.conf

package: igmpproxy

title: igmpproxy.conf(5)

summary: Configuration file for

text:
# igmpproxy.conf(5)

## NAME
igmpproxy.conf - Configuration file for igmpproxy(8) multicast daemon

## DESCRIPTION
igmpproxy.conf contains the configuration for the igmpproxy multicast daemon. It defines which network interfaces should be used by the routing daemon. Each interface must be give one of the following roles: upstream , downstream or disabled

The upstream network interface is the outgoing interface which is responsible for communicating to availible multicast data sources. There can only be one upstream interface.

Downstream network interfaces are the distribution interfaces to the destination networks, where multicast clients can join groups and receive multicast data. One or more downstream interfaces must be configured.

On disabled network interfaces all IGMP or multicast traffic is ignored altogether. If multiple IP addresses is used on one single interface (ae. eth0:1 ...), all interface aliases not in use should be configured as disabled.

Any line in the configuration file starting with # is treated as a comment. Keywords and parameters can be distributed over many lines. The configuration file has two main keywords:

quickleave

Enables quickleave mode. In this mode the daemon will send a Leave IGMP message upstream as soon as it recieves a Leave message for any downstream interface. The daemon will then ask for Membership reports on the downstream interfaces, and if a report is recieved the group is joined again upstream. Normally this is not noticed at all by clients on the downstream networks. If it's vital that the daemon should act exactly as a real multicast client on the upstream interface, this function should not be used. Disabling this function increases the risk of bandwidth saturation.

phyint interface role [ ratelimit limit ] [ threshold ttl ] [ altnet networkaddr ... ]

Defines the state and settings of a network interface.

## PHYINT OPTIONS
interface

The name of the interface the settings are for. This option is required for phyint settings.

role

The role of the interface. This should be either upstream (only one interface), downstream (one or more interfaces) or disabled

ratelimit limit

Defines a ratelimit for the network interface. If ratelimit is set to 0 (default), no ratelimit will be applied. This setting is optional.

threshold ttl

Defines the TTL threshold for the network interface. Packets with a lower TTL than the threshols value will be ignored. This setting is optional, and by default the threshold is 1.

altnet networkaddr

Defines alternate sources for multicasting and IGMP data. The network address must be on the following format 'a.b.c.d/n'. By default the router will accept data from sources on the same network as configured on an interface. If the multicast source lies on a remote network, one must define from where traffic should be accepted. This is especially useful for the upstream interface, since the source for multicast traffic is often from a remote location. Any number of altnet parameters can be specified.

whitelist networkaddr

Defines a whitelist for multicast groups. The network address must be in the following format 'a.b.c.d/n'. If you want to allow one single group use a network mask of /32, i.e. 'a.b.c.d/32'. By default all multicast groups are allowed on any downstream interface. If at least one whitelist entry is defined, all igmp membership reports for not explicitly whitelisted multicast groups will be ignored and therefore not be served by igmpproxy. This is especially useful, if your provider does only allow a predefined set of multicast groups. These whitelists are only obeyed by igmpproxy itself, they won't prevent any other igmp client running on the same machine as igmpproxy from requesting 'unallowed' multicast groups.

You may specify as many whitelist entries as needed. Although you should keep it as simple as possible, as this list is parsed for every membership report and therefore this increases igmp response times. Often used or large groups should be defined first, as parsing ends as soon as a group matches an entry.

You may also specify whitelist entries for the upstream interface. Only igmp membership reports for explicitely whitelisted multicast groups will be sent out on the upstream interface. This is useful if you want to use multicast groups only between your downstream interfaces, like SSDP from a UPnP server.

## EXAMPLE
\## Enable quickleave quickleave

\## Define settings for eth0 (upstream)

phyint eth0 upstream

altnet 10.0.0.0/8

\## Disable alternate IP on eth0 (eth0:0)

phyint eth0:0 disabled

\## Define settings for eth1 (downstream)

phyint eth1 downstream ratelimit 0 threshold 1

\## Define settings for eth2 (also downstream)

phyint eth2 downstream

## SEE ALSO
igmpproxy(8)

## AUTHOR
Originally written by Johnny Egeland <johnny@rlo.org>


package: imapfilter

title: imapfilter_config(5)

summary: imapfilter configuration file

text:
# imapfilter_config(5)

## NAME
imapfilter_config — imapfilter configuration file

## SYNOPSIS
$HOME/.imapfilter/config.lua

## DESCRIPTION
imapfilter(1) uses the Lua programming language as a configuration and extension language, therefore the configuration file is a Lua script.

Although knowledge of Lua is not required to use imapfilter(1), it is nonetheless recommended, especially if one wants to extend it. For more information on Lua see http://www.lua.org/docs.html.

## CONVENTIONS
A brief description of the Lua values and types mentioned hereafter in the manual page follows:

- The nil is the type of the value “nil”, whose main property is to be different from any other value; usually it represents the absence of a useful value.

- The boolean is the type of the values “true” and “false”. Both “nil” and “false” make a condition false; any other value makes it true.

- The type number represents real numbers.

- The type string represents a sequence of characters and can be defined using single quotes, double quotes or double square brackets.

- The type table implements associative arrays, that is, arrays that can be indexed not only with numbers, but with any value.

- A function is a first-class value; it can be stored in variables, passed as argument to other functions, and returned as a result.

## OPTIONS
Program's options are set using an already initialised table named “options”, in the following manner:

```
options.timeout = 120
options.namespace = false
options.charset = 'ISO-8859-1'
```

Available options are:

cache

When this option is enabled, parts of messages are cached locally in memory to avoid being downloaded more than once. The cache is preserved for the current session only. This variable takes a boolean as a value. Default is “true”.

certificates

When this option is enabled, the server certificate can be accepted and stored, in order to validate the authenticity of the server in future connections. This variable takes a boolean as a value. Default is “true”.

charset

Indicates to the server the character set of the strings for the searching methods. This variable takes a string as a value. By default no character set is set, and thus plain ASCII should be assumed by the server.

create

According to the IMAP specification, when trying to write a message to a non-existent mailbox, the server must send a hint to the client, whether it should create the mailbox and try again or not. However some IMAP servers don't follow the specification and don't send the correct response code to the client. By enabling this option the client tries to create the mailbox, despite of the server's response. This variable takes a boolean as a value. Default is “false”.

close

This option controls whether the currently selected mailbox is implicitly closed at the end of each performed operation, thus removing all messages that are marked deleted. This variable takes a boolean as a value. Default is “false”.

crammd5

When this option is enabled and the server supports the Challenge-Response Authentication Mechanism (specifically CRAM-MD5), this method will be used for user authentication instead of a plaintext password LOGIN. This variable takes a boolean as a value. Default is “true”.

expunge

Normally, messages are marked for deletion and are actually deleted when the mailbox is closed. When this option is enabled, messages are expunged immediately after being marked deleted. This variable takes a boolean as a value. Default is “true”.

hostnames

When this option is enabled, the server hostname is validated, in order to verify the client is talking to the correct server. This variable takes a boolean as a value. Default is “true”.

info

When this options is enabled, a summary of the program's actions is printed, while processing mailboxes. This variable takes a boolean as a value. Default is “true”.

keepalive

The time in minutes before terminating and re-issuing the IDLE command, in order to keep alive the connection, by resetting the inactivity timeout of the server. A standards compliant server must have an inactivity timeout of at least 30 minutes. But it may happen that some IMAP servers don't respect that, or some intermediary network device has a shorter timeout. By setting this option the above problem can be worked around. This variable takes a number as a value. Default is “29” minutes.

limit

Some servers have problems handling very long requests, but some of the requests that need to be sent can become quite long, because they apply an action for many messages at once. When this option is set, the client will try to break up these requests into smaller requests, that each operates on fewer messages at a time. A good value for this would be “50”. This variable takes a number as a value. Default is “0”. See also the range option which is related.

namespace

When enabled, the program gets the namespace of the user's personal mailboxes, and applies automatically the prefix and hierarchy delimiter to any mailboxes residing on the mail server; the user must use the ‘/’ character as the delimiter and “” (ie. nothing) as the prefix, regardless of the folder format of the mail server. This must be disabled, if the user wants to manually specify mailbox names (eg. because they are not part of the user's personal namespace mailboxes). This variable takes a boolean as a value. Default is “true”.

persist

When the recover option is enabled, the recovery function tries to restore the lost session, but if it fails to do so it gives up with an error. In some cases a temporary network problem might cause the recovery function to fail, but the connection could be reestablished when trying a bit later. By enabling this option, the recovery function will be called repeatedly after a timeout, thus it will persist when trying to restore the session. Note, that this will case the execution of the configuration file to be halted at the point of failure until the session is restored, which can have side effects to other established sessions, for example they might get dropped by the server after a while. This variable takes a boolean as a value. Default is “false”.

range

Some servers have problems handling long sequence number ranges, and by setting this option, the number of messages included in each range can be limited. A good value for this would be “50”. This variable takes a number as a value. By default no such limit is imposed. See also the limit option which is related.

recover

With this option it is possible to control the recovery functionality, which restores a session (the connection to the server and the IMAP state at the time), after some unexpected event takes place. Currently there are two types of events that can end abnormally a session, and finally cause the program to terminate: network errors, and the IMAP BYE response which a server can send anytime. When this option is set to “all” the recovery function is triggered by both types of events, when set to “errors” only in the case of network errors, and when set to “none” the mechanism is completely disabled. Default is “all”.

reenter

When this option is enabled and the connection is recovered after some unexpected event while in IDLE mode (see also the recover option), the client will re-enter IDLE mode. But when this option is disabled, and after the connection is recovered, the client will not re-enter IDLE mode, and instead will continue to execute the next line in the configuration file, ie. the one after enter_idle(). Default is “true”.

starttls

When this option is enabled and the server supports the IMAP STARTTLS extension, a TLS connection will be negotiated with the mail server in the beginning of the session. This variable takes a boolean as value. Default is “true”.

subscribe

By enabling this option new mailboxes that were automatically created, get also subscribed; they are set active in order for IMAP clients to recognize them. This variable takes a boolean as a value. Default is “false”.

timeout

The time in seconds for the program to wait for a mail server's response. If set to 0, the client will block indefinitely. This variable takes a number as a value. Default is “60” seconds.

wakeonany

By enabling this option the IDLE command will return on any event that is received from the server, and not just on the “RECENT” and “EXISTS” events, that normally indicate the arrival of a new message. Examples of other events are “FETCH”, which indicates that the details of a message (eg. its flags) have been modified, or “EXPUNGE”, which indicates that a message has been deleted. This variable takes a boolean as a value. Default is “false”.

## ACCOUNTS
Accounts are initialized using the IMAP() function, and the details of the connection are defined using an account table:

```
myaccount = IMAP {
    server = 'imap.mail.server',
    username = 'me',
    password = 'secret',
    ssl = 'auto'
}
```

An account table must have the following elements:

server

The hostname of the IMAP server to connect to. It takes a string as a value.

username

User's name. It takes a string as a value.

An account table can also have the following optional elements:

password

User's secret keyword. If a password wasn't supplied the user will be asked to enter one interactively the first time it will be needed (unless oauth2 has been set). It takes a string as a value. Note that due to Lua using backslash ‘\’ as an escape character for its strings, one has to use double backslashes in order to insert a single backslash, and thus a backslash character inside a password might require four backslashes.

oauth2

The OAuth2 string to use to authenticate if the server supports the XOAUTH2 authentication mechanism. If the server does not support it and a password has been also set, authentication will be attempted using the password. It takes a string as a value. Note that this requires that an OAuth client ID and client secret have been obtained, an OAuth2 token has been generated and authorized, a new access token has been generated using the refresh token if the last access token has expired, and an OAuth2 string has been generated from the access token. The aforementioned OAuth2 string is a Base64 encoded string that should be set here. For more information see https://developers.google.com/gmail/xoauth2_protocol.

port

The port to connect to. It takes a number as a value. Default is “143” for imap and “993” for imaps.

ssl

Forces an imaps connection and specifies the SSL/TLS protocol/version to be used. It takes a string as a value, specifically one of: “auto”, “tls1.2”, “tls1.1”, “tls1”, “ssl3”. Note that the latest versions of the OpenSSL library have deprecated version specific methods, and the actual protocol version used will be negotiated to be the highest version mutually supported by the client and the server. This is also what the “auto” value does.

### LISTING
The following methods can be used on an account to list mailboxes in a folder of an account:

list_all(folder)

Lists all the available mailboxes in the folder (string), and returns a table that contains strings, the available mailboxes, and a table that contains strings, the available folders.

list_subscribed(folder)

Lists all the subscribed mailboxes in the folder (string), and returns a table that contains strings, the subscribed mailboxes, and a table that contains strings, the subscribed folders.

The following methods can be used on an account to list mailboxes, using wildcards, in a folder of an account. The ‘*’ wildcard, matches any character and the ‘%’ matches any character except the folder delimiter, ie. non-recursively:

list_all(folder, mailbox)

Lists all the available mailboxes in the folder (string) with the name mailbox (string), and returns a table that contains strings, the available mailboxes, and a table that contains strings, the available folders. Wildcards may only be used in the mailbox argument.

list_subscribed(folder, mailbox)

Lists all the subscribed mailboxes in the folder (string) with the name mailbox (string), and returns a table that contains strings, the subscribed mailboxes, and a table that contains strings, the subscribed folders. Wildcards may only be used in the mailbox argument.

Examples:

```
mailboxes, folders = myaccount:list_subscribed('myfolder')
mailboxes, folders = myaccount:list_all('myfolder/mysubfolder', '*')
```

### MANIPULATING
The following methods can be used to manipulate mailboxes in an account:

create_mailbox(name)

Creates the name (string) mailbox.

delete_mailbox(name)

Deletes the name (string) mailbox.

rename_mailbox(oldname, newname)

Renames the oldname (string) mailbox to newname (string).

subscribe_mailbox(name)

Subscribes the name (string) mailbox.

unsubscribe_mailbox(name)

Unsubscribes the name (string) mailbox.

Examples:

```
myaccount:create_mailbox('mymailbox')
myaccount:subscribe_mailbox('mymailbox')
myaccount:unsubscribe_mailbox('myfolder/mymailbox')
myaccount:delete_mailbox('myfolder/mymailbox')
```

## MAILBOXES
After an IMAP account has been initialized, mailboxes residing in that account can be accessed simply as elements of the account table:

```
myaccount.mymailbox
```

If mailbox names don't only include letters, digits and underscores, or begin with a digit, an alternative form must be used:

```
myaccount['mymailbox']
```

A mailbox inside a folder can be only accessed by using the alternative form:

```
myaccount['myfolder/mymailbox']
```

The methods that are available for an account (eg. list_all(), create_mailbox(), etc.) , are considered keywords and must not be used as mailbox names, and the same also applies for any string starting with an underscore, as they are considered reserved.

### CHECKING
The following methods can be used to check the status of a mailbox:

check_status()

The check_status() method gets the current status of a mailbox, and returns four values of number type: the total number of messages, the number of recent messages, the number of unseen messages in the mailbox, and the next UID to be assigned to a new message in the mailbox.

enter_idle()

The enter_idle() method implements the IMAP IDLE (RFC 2177) extension. By using this extension it's not necessary to poll the server for changes to the selected mailbox (ie. using the check_status() method), but instead the server sends an update when there is a change in the mailbox (eg. in case of new mail). When the enter_idle() method has been called no more commands in the configuration file are executed until an update is received, at which point the enter_idle() method returns. For the enter_idle() to work, the IDLE extension has to be supported by the IMAP server. The enter_idle() method returns a value of type boolean: “true” if the IDLE extension is supported and there was a update in the mailbox, and “false” if the IDLE extension is not supported, in which case the method returns immediately. When the aforementioned return value was “true”, an additional second value of type string is also returned, indicating the event received from the server, which is useful when the wakeonany option has been enabled.

Apart from an event received by the server, the SIGUSR1 or SIGUSR2 signals can also interrupt the IDLE mode at any time, and the execution of the configuration file will then continue from the next line after the enter_idle(). In this case only the value “true” is returned.

Examples:

```
exist, unread, unseen, uidnext = myaccount.mymailbox:check_status()
update = myaccount.mymailbox:enter_idle()
update, event = myaccount.mymailbox:enter_idle()
```

### SEARCHING
The searching methods in this subsection can be applied to any mailbox. They return a special form of table, that contains the messages that match the searching method. This table can be combined with other tables using logic theory. There are three available operations, that implement logical “or”, logical “and” and logical “not”.

The logical “or” is implemented using the ‘+’ operator:

```
results = myaccount.mymailbox:is_unseen() +
          myaccount.mymailbox:is_larger(100000)
```

The logical “and” is implemented using the ‘*’ operator:

```
results = myaccount.mymailbox:is_unseen() *
          myaccount.mymailbox:is_larger(100000)
```

The logical “not” is implemented using the ‘-’ operator:

```
results = myaccount.mymailbox:is_unseen() -
          myaccount.mymailbox:is_larger(100000)
```

The three logical operators can be combined in the same expression. The logical “and” has higher precedence than the logical “or” and the logical “not”, with the latter two having the same precedence, and parentheses may be used to change this behaviour:

```
results = myaccount.mymailbox:is_unseen() +
          myaccount.mymailbox:is_larger(100000) *
          myaccount.mymailbox:contain_subject('test')

results = ( myaccount.mymailbox:is_unseen() +
            myaccount.mymailbox:is_larger(100000) ) *
            myaccount.mymailbox:contain_subject('test')
```

The returned tables of the searching methods can also be stored in variables and then further processed:

```
unseen = myaccount.myaccount:is_unseen()
larger = myaccount.mymailbox:is_larger(100000)
subject = myaccount.mymailbox:contain_subject('test')
results = unseen + larger * subject
```

A composite filter that includes one or more simple rules can be defined:

```
myfilter = function ()
	       return myaccount.mymailbox:is_unseen() +
	              myaccount.mymailbox:is_larger(100000) *
                      myaccount.mymailbox:contain_subject('test')
           end

results = myfilter()
```

Composite filters can may be more dynamic by adding arguments:

```
myfilter = function (mailbox, size, subject)
	       return mailbox:is_unseen() +
                      mailbox:is_larger(size) *
                      mailbox:contain_subject(subject)
           end

results = myfilter(myaccount.mailbox, 100000, 'test')
```

It is also possible to combine the searching methods in different mailboxes, either at the same or different accounts, for example when the same actions will be executed on messages residing in different mailboxes or accounts.

```
results = myaccount.mymailbox:is_unseen() +
	  myaccount.myothermailbox:is_larger(100000) +
	  myotheraccount.myothermailbox:contain_subject('test')
```

And for those that want to know more about the return values of the following methods, it is a table which contains tables with two values: the mailbox (table) the message belongs to, and the message UID (number) which points to the matching message. For examples on iterating these returned tables, or creating new tables of this format (they are actually metatables implementing sets), see the samples/extend.lua file.

```
{
    { <myaccount.mymailbox>, 1 },
    { <myaccount.mymailbox>, 3 },
    { <myaccount.myothermailbox>, 5 },
    { <myothermailbox.myothermailbox>, 7},
    { ... },
    ...
}
```

The following method can be used to get all messages in a mailbox:

select_all()

All messages.

The following methods can be used to search for messages that are in a specific state:

is_answered()

Messages that have been answered.

is_deleted()

Messages that are marked for later removal.

is_draft()

Messages that have not completed composition.

is_flagged()

Messages that are flagged for urgent/special attention.

is_new()

Messages that are recently arrived (this session is the first to have been notified about these messages) and have not been read.

is_old()

Messages that are not recently arrived (this session is not the first to have been notified about these messages) and have not been read.

is_recent()

Messages that are recently arrived (this session is the first to have been notified about these messages).

is_seen()

Messages that have been read.

is_unanswered()

Messages that have not been answered.

is_undeleted()

Messages that are not marked for later removal.

is_undraft()

Messages that have completed composition.

is_unflagged()

Messages that are not flagged for urgent/special attention.

is_unseen()

Messages that have not been read.

The following method can be used to search for messages that have a specific keyword flag set:

has_keyword(flag)

Messages with the specified keyword flag (string) set.

has_unkeyword(flag)

Messages without the specified keyword flag (string) set.

The following methods can be used to search for messages based on their size:

is_larger(size)

Messages that are larger than the size (number) in octets (bytes).

is_smaller(size)

Messages that are smaller than the size (number) in octets (bytes).

The following methods can be used to search for messages based on their age:

is_newer(age)

Messages that are newer than the age (number) in days.

is_older(age)

Messages that are older than the age (number) in days.

The following methods can be used to search for messages based on their arrival or sent date, in the “day-month-year” form, where day is the day of the month as a decimal number (01-31), month is the abbreviated month ( “Jan”, “Feb”, “Mar”, “Apr”, “May”, “Jun”, “Jul”, “Aug”, “Sep”, “Oct”, “Nov”, “Dec”) and year is the year as decimal number including the century (eg. 2007):

arrived_before(date)

messages that have arrived earlier than the date (string), where date is in the “day-month-year” form.

arrived_on(date)

Messages that have arrived within the date (string), where date is in the “day-month-year” form.

arrived_since(date)

Messages that have arrived within or later than the date (string), where date is in the “day-month-year” form.

sent_before(date)

Messages that have been sent earlier than the date (string), where date is in the “day-month-year” form.

sent_on(date)

Messages that have been sent within the date (string), where date is in the “day-month-year” form.

sent_since(date)

Messages that have been sent within or later than the date (string), where date is in the “day-month-year” form.

The following methods can be used to do case-insensitive searching, for messages that contain a specific word or phrase:

contain_bcc(string)

Messages that contain the string (string) in the “Bcc” header field.

contain_cc(string)

Messages that contain the string (string) in the “Cc” header field.

contain_from(string)

Messages that contain the string (string) in the “From” header field.

contain_subject(string)

Messages that contain the string (string) in the “Subject” header field.

contain_to(string)

Messages that contain the string (string) in the “To” header field.

contain_field(field, string)

Messages that contain the string (string) in the field (string) header field.

contain_body(string)

Messages that contain the string (string) in the message body.

contain_message(string)

Messages that contain the string (string) in the message.

The following methods can be used to do case-sensitive searching, for messages that match a specific regular expression pattern. The matching mechanism that is used to support this is based on the Perl-compatible regular expressions (PCRE), and more information about the patterns and modifiers that can be used, is available in the relevant documentation at http://pcre.org/original/doc/html/.

This way of searching is not supported by the IMAP protocol, and this means that what actually happens under the hood, is that the relevant parts of all the messages are downloaded and matched locally. It is therefore recommended to use these methods with meta-searching (see following section), in order to narrow down the set of messages that should be searched, and thus minimize what will be downloaded.

Note that due to Lua using backslash ‘\’ as an escape character for its strings, one has to use double backslashes in order to insert a single backslash inside a regular expression pattern:

match_bcc(pattern)

Messages that match the regular expression pattern (string) in the “Bcc” header field.

match_cc(pattern)

Messages that match the regular expression pattern (string) in the “Cc” header field.

match_from(pattern)

Messages that match the regular expression pattern (string) in the “From” header field.

match_subject(pattern)

Messages that match the regular expression pattern (string) in the “Subject” header field.

match_to(pattern)

Messages that match the regular expression pattern (string) in the “To” header field.

match_field(field, pattern)

Messages that match the regular expression pattern (string) in the field (string) header field.

match_header(pattern)

Messages that match the regular expression pattern (string) in the message header.

match_body(pattern)

Messages that match the regular expression pattern (string) in the message body.

match_message(pattern)

Messages that match the regular expression pattern (string) in the message.

The following method can be used to search for messages using user queries based on the IMAP specification (RFC 3501 Section 6.4.4):

send_query(criteria)

Searches messages by sending an IMAP search query as described in the search criteria (string).

Examples:

```
results = myaccount.mymailbox:select_all()
results = myaccount.mymailbox:is_new()
results = myaccount.mymailbox:is_recent()
results = myaccount.mymailbox:is_larger(100000)
results = myaccount.mymailbox:is_older(10)
results = myaccount.mymailbox:has_keyword('MyFlag')
results = myaccount.mymailbox:arrived_before('01-Jan-2007')
results = myaccount.mymailbox:sent_since('01-Jan-2007')
results = myaccount.mymailbox:contain_subject('test')
results = myaccount.mymailbox:contain_field('Sender', 'user@host')
results = myaccount.mymailbox:contain_body('hello world')
results = myaccount.mymailbox:match_from('.*(user1|user2)@host')
results = myaccount.mymailbox:send_query('ALL')

results = myaccount['mymailbox']:is_new()
results = myaccount['myfolder/mymailbox']:is_recent()
```

## RESULTS
After one of more searching methods have been applied to one or more mailboxes, the result contains all the necessary information, such as which messages matched in which mailboxes. Using this result these messages can be either searched further or processed in various way.

### META-SEARCHING
The results of the searching methods can be searched further on in the same way as searching is done in mailboxes. The difference is that instead of doing the search in the whole mailbox, ie. in all the messages, it is instead done only to those messages that were returned in a previous search.

Examples:

```
results:match_message('^[Hh]ello world!?$')
myaccount.mymailbox:is_new():match_body('^[Ww]orld, hello!?$')
```

### PROCESSING
The processing methods are applied to the results that searching returned.

The following method can be used to delete messages in a mailbox:

delete_messages()

Deletes the messages that matched.

The following methods can be used to copy and move messages in a mailbox at the same or different accounts. If the destination mailbox is in a different account than the source mailbox, then the messages are downloaded and then uploaded to the destination:

copy_messages(destination)

Copies the messages to the destination, which is a mailbox at an account.

move_messages(destination)

Moves the messages to the destination, which is a mailbox at an account.

The following methods can be used to mark messages in a mailbox:

mark_answered()

Marks the messages as answered.

mark_deleted()

Marks the messages for later removal.

mark_draft()

Marks the messages as draft.

mark_flagged()

Marks the messages for urgent/special attention.

mark_seen()

Marks the messages as read.

unmark_answered()

Unmarks the messages that have been marked as answered.

unmark_deleted()

Unmarks the messages that have been marked for later removal.

unmark_draft()

Unmarks the messages that have been marked as draft.

unmark_flagged()

Unmarks the messages that have been marked for urgent/special attention.

unmark_seen()

Unmarks the messages that have been marked as read.

The following methods can be used to flag messages in a mailbox. The standard system flags are “\Answered”, “\Deleted”, “\Draft”, “\Flagged”, “\Seen”, while if the server supports it, new user keywords may be defined:

add_flags(flags)

Adds the flags (table that contains strings) to the messages.

remove_flags(flags)

Removes the flags (table that contains strings) from the messages.

replace_flags(flags)

Replaces the flags (table that contains strings) of the messages.

Examples:

```
results:delete_messages()
results:copy_messages(myaccount.myothermailbox)
results:move_messages(myotheraccount.mymailbox)
results:mark_seen()
results:unmark_flagged()
results:add_flags({ 'MyFlag', '\\Seen' })
results:remove_flags({ '\\Seen' })

results:move_messages(myotheraccount['myfolder/mymailbox'])
```

## MESSAGES
The messages that are residing in any mailbox can be also accessed, as a whole or in parts. Messages can be accessed using their unique identifier (UID):

```
myaccount.mymailbox[22]
```

The UIDs of messages the user is interested in, are gained from the results of searching:

```
results = account.INBOX:is_unseen()
for _, message in ipairs(results) do
    mailbox, uid = table.unpack(message)
    header = mailbox[uid]:fetch_header()
end
```

### FETCHING
The following methods can be used to fetch parts of messages. The methods return a string. The downloaded message parts are cached locally, so they can be reused inside the same program session:

fetch_message()

Fetches the header and body of the message.

fetch_header()

Fetches the header of the message.

fetch_body()

Fetches the body of the messages.

fetch_field(field)

Fetches the specified header field (string) of the message.

fetch_part(part)

Fetches the specified part (string) of the message.

The following methods can be used to fetch details about the state of a message:

fetch_flags()

Fetches the flags of the message. Returns a table of strings.

fetch_date()

Fetches the internal date of the message. Returns a string.

fetch_size()

Fetches the size of the message. Returns a number.

fetch_structure()

Fetches the body structure of the message. Returns a table that has as keys the parts of the message, and as values a table that has one mandatory element, the type (string) of the part, and two optional elements, the size (number) and name (string) of the part.

### APPENDING
The following methods can be used to append a message to a mailbox:

append_message(message)

Appends the message (string) to the mailbox.

append_message(message, flags, date)

Appends the message (string) to the mailbox, setting the specified flags (table of strings), as returned by fetch_flags(), and date (string), as returned by fetch_date().

Examples:

```
myaccount.mymailbox[2]:fetch_message()
myaccount.mymailbox[3]:fetch_field('subject')
myaccount.mymailbox[5]:fetch_part('1.1')

myaccount['mymailbox'][7]:fetch_message()
myaccount['myfolder/mymailbox'][11]:fetch_message()

myaccount.mymailbox:append_message(message)
```

## FUNCTIONS
The following auxiliary functions are also available for convenience:

form_date(days)

Forms a date in “day-month-year” format that the system had before the number of days (number), and returns it as a string.

get_password(prompt)

Displays the specified prompt (string), and reads a password, while character echoing is turned off. Returns that password as a string.

become_daemon(interval, commands)

Detaches the program from the controlling terminal and runs it in the background as system daemon. The program will then repeatedly poll at the specified interval (number) in seconds. Each time the program wakes up, the commands (function) are executed.

become_daemon(interval, commands, nochdir, noclose)

Detaches the program from the controlling terminal and runs it in the background as system daemon. The program will then repeatedly poll at the specified interval (number) in seconds. Each time the program wakes up, the commands (function) are executed. If nochdir (boolean) is “true”, the current working directory is not changed to the root directory (/). If noclose (boolean) is “true”, the standard input, standard output and standard error are not redirected to /dev/null.

pipe_to(command, data)

Executes the system's command (string) and sends the data (string) to the standard input channel of the subprocess. Returns a number, the exit status of the child process.

pipe_from(command)

Executes the system's command (string) and retrieves the data from the standard output channel of the subprocess. Returns a number, the exit status of the child process, and a string, the output of the child process.

regex_search(pattern, string)

Implements Perl-compatible regular expressions (PCRE). The pattern (string) is a PCRE pattern. The string (string) is the subject string in which the pattern is matched against. Returns at least a boolean, that denotes if the match was successful, and any captures which are of string type. Note that due to Lua using backslash ‘\’ as an escape character for its strings, one has to use double backslashes in order to insert a single backslash inside a regular expression pattern. For more information on PCRE see http://pcre.org/original/doc/html/.

Examples:

```
date = form_date(14)
password = get_password('Enter password: ')
become_daemon(600, myfunction)
status = pipe_to('mycommandline', 'mydata')
status, data = pipe_from('mycommandline')
success, capture = regex_search('^(?i)pcre: (\\w)$', 'mystring')
```

## EXAMPLES
See samples/config.lua and samples/extend.lua in the source code distribution.

## ENVIRONMENT
HOME

User's home directory.

## SEE ALSO
imapfilter(1)


imv

package: imv

title: imv(5)

summary: imv configuration file

text:
# imv(5)

## NAME
imv - imv configuration file

## DESCRIPTION
imv can be customised with this configuration file, changing its default behaviour, key bindings, and appearance.

The imv configuration file is an ini-style file, with multiple key = value settings, separated into several '[section]'s.

## OPTIONS
The [options] section accepts the following settings:

background = <hex-code|checks>

Set the background in imv. Can either be a 6-digit hexadecimal colour code, or checks for a chequered background. Defaults to 000000

fullscreen = <true|false>

Start imv fullscreen. Defaults to false.

width = <width>

Initial width of the imv window. Defaults to 1280.

height = <height>

Initial height of the imv window. Defaults to 720.

initial_pan = <pan_factor_x> <pan_factor_y>

Initial pan/focus position factor of the opened images. A value of 50 represents the middle point of the image (50%). Defaults to 50 50

list_files_at_exit = <true|false>

Print open files to stdout at exit, each on a separate line. Defaults to false.

loop_input = <true|false>

Return to first image after viewing the last one. Defaults to true.

overlay = <true|false>

Start with the overlay visible. Defaults to false.

overlay_font = <typeface:size>

Use the specified font in the overlay. Defaults to Monospace:24.

overlay_text = <text>

Use the given text as the overlay’s text. The provided text is shell expanded, so the output of commands can be used (for example, $(ls)). Environment variables can also be used, including the ones accessible to imv’s exec command.

overlay_text_color = <hex-code>

Set the color for the text in the overlay. Is a 6-digit hexadecimal color code. Defaults to ffffff.

overlay_text_alpha = <hex-code>

Set the alpha for the text in the overlay. Is a 2-digit hexadecimal color code. Defaults to ff.

overlay_background_color = <hex-code>

Set the color for the background of the overlay. Is a 6-digit hexadecimal color code. Defaults to 000000.

overlay_background_alpha = <hex-code>

Set the alpha for the background of the overlay. Is a 2-digit hexadecimal color code. Defaults to c3.

overlay_position_bottom = <true|false>

Display the overlay at the bottom of the imv window, instead of the top.

recursively = <true|false>

Load input paths recursively. Defaults to false.

scaling_mode = <none|shrink|full|crop>

Set scaling mode to use. none will show each image at its actual size. shrink will scale down the image to fit inside the window. full will both scale up and scale down the image to fit perfectly inside the window. crop will scale and crop the image to fill the window. Defaults to full.

slideshow_duration = <duration>

Start imv in slideshow mode, and set the amount of time to show each image for in seconds. Defaults to 0, i.e. no slideshow.

suppress_default_binds = <true|false>

Disable imv’s built-in binds so they don’t conflict with custom ones. Defaults to false.

title_text = <text>

Use the given text as the window’s title. The provided text is shell expanded, so the output of commands can be used: $(ls) as can environment variables, including the ones accessible to imv’s exec command.

upscaling_method = <linear|nearest_neighbour>

Use the specified method to upscale images. Defaults to linear.

## ALIASES
The [aliases] section allows aliases to be added for imv’s build in commands. For example, x = close would add a x command that simply executes the close command. Any arguments provided to an alias are appended to the command configured by the alias.

## BINDS
The [binds] section allows custom key bindings to be added to imv.

Binds are in the format key combination = command. A key combination can consist of multiple keys in succession. Multiple commands for a single key combination can be defined by separating each command with a ;. Single and double quotes are honoured, as is escaping with a backslash, to allow the proper quoting of shell commands.

Single keys such as q are just that: q = quit will bind the q key to the quit command.

Modifier keys can be specified by prefixing them: Ctrl+q, Meta+f, Shift+G. If multiple modifier keys are desired, they are specified in the order Ctrl+Meta+Shift. When a key’s name is more than a single character, or a modifier is used it must be wrapped in < and >, for example: <Ctrl+q>.

Multiple keys in succession can be specified by listing them in order: gg = goto 1 will bind two presses of the g key to jump to the first image, and <Ctrl+a>p = exec echo hi will bind the key sequence of Ctrl+a followed by p to executing the shell command echo hi.

Many keys, such as <, and > have special names. On X11, these can be easily found with the xev(1) command. For example, ! is called exclam, < is called less, > is called greater.

A complete list of keysyms can also be found on most systems with the dumpkeys -l command.

imv(1)


incron.conf

package: incron

title: incron.conf(5)

text:
# incron.conf(5)

## NAME
/etc/incron.conf - main config file for inotify cron (incron)

## DESCRIPTION
The file /etc/incron.conf contains default settings for the program incrond. Each line holds a single value pair in the form option = value. Comment lines must have a hash sign (#) in the first line.

The valid configuration options are:

system_table_dir

This directory is examined by incrond for system table files. Default:/etc/incron.d

user_table_dir

This directory is examined by incrond for user table files. Default:/var/spool/incron

allowed_users

This file contains users allowed to use incron. Default:/etc/incron.allow

denied_users

This file contains users denied to use incron. Default:/etc/incron.deny

lockfile_dir

This directory is used for creating a lock avoiding to run multiple instances of incrond. Default:/var/run

lockfile_name

This name (appended by '.pid') is used for creating a lock avoiding to run multiple instances of incrond. Default:incrond

editor

This name or path is used to run as an editor for editing incron tables. Default no editor is given, system editor used, this option overide this.

## SEE ALSO
incrond(8), incrontab(1), incrontab(5)

## AUTHOR
Andreas Altair Redmer <altair.ibn.la.ahad.sy@gmail.com> (please report bugs to https://github.com/ar-/incron/issues ). Lukas Jelinek <lukas@aiken.cz>.

## COPYING
This program is free software. It can be used, redistributed and/or modified under the terms of the GNU General Public License, version 2.