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 which 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 fte fte fte
     prog vim vim gvim
     prog xemacs xemacs xemacs
     prog emacs emacs emacs
     prog NEdit nedit nedit
     prog xedit xedit xedit
     prog Lyx emacs lyx
 }
 menu "WWW" folder {
     prog Netscape netscape netscape
     prog Mozilla mozilla mozilla
     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 "Acrobat Reader" pdf acroread
     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 "Koules for X" koules xkoules -f
     prog Xboing xboing xboing
     prog Xboard xboard xboard
     prog XGalaga xgalaga xgal
     prog XDemineur xdemineur xdemineur
     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 which 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".

### 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="default/default.theme"".

### EXAMPLES
Following is my current theme file. You can see from the comments that icewm(1) keeps a history of the previous ten theme settings.

```
    Theme="Unexicon-towers/default.theme"
    #Theme="Unexicon-pedestals/default.theme"
    ##Theme="Unexicon-penguins/default.theme"
    ###Theme="Unexicon/default.theme"
    ####Theme="Squared-for-debian/default.theme"
    #####Theme="Squared-grey/default.theme"
    ######Theme="Squared-green/default.theme"
    #######Theme="Penguins/default.theme"
    ########Theme="Squared-blue/default.theme"
    #########Theme="default/default.theme"
    ##########Theme="yellowmotif/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 which 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
Contains settings to control window appearance and behaviour. These are specific to applications, or to groups of applications. Options can control the window border, whether the application appears on the task bar, the window list, the system tray and the work spaces. Also its layer, geometry, whether it can be moved, resized and closed.

Options 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.

### 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

Where the fields are defined as follows:

CLASS

The resource class portion of the ICCCM WM_CLASS property for the window.

NAME

The resource instance portion of the ICCCM WM_CLASS property for the window.

ROLE

The ICCCM WM_WINDOW_ROLE property for the window.

OPTION: VALUE

One of the options and values described below under "OPTIONS".

Note that it is possible that the WM_WINDOW_ROLE may contain a period ("."). When it does, the period should be escaped by a single backslash when specifying the ROLE in the file.

### OPTIONS
The options and values described in the format, above, consist of an option name, OPTION followed by a semicolon (":") a space (" ") and an allowable value for the option, VALUE. The available options are as follows:

### GENERAL OPTIONS
The following option control general characteristics of windows:

icon: NAME (default: none)

Specifies the icon name for the window. NAME is the name of the icon, 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: {Desktop|Below|Normal|OnTop|Dock|AboveDock|Menu|NUMBER} (default: 4)

Specifies the default layer for the window. Layer can be one of the following strings or a number from zero (0) to fifteen (15):

```
  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)  Windows above the dock.

```

geometry geometry (default: WM_SIZE_HINTS)

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>]

```

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 strings or a number from zero (0) to two (2):

```
  Ignore     (0)  No icon added to 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 of task buttons and tray icons. The default value is zero. Increasing positive values go farther right, while decreasing negative values go farther left. The order option applies to the task pane, the tray pane and the system tray.

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. The following options are defined:

```
  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. The following options are defined:

```
  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. The following options are defined:

```
  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.
  forcedClose:              {1|0}  no close dialog.
  fullKeys:                 {1|0}  provided more keys.
  ignoreNoFocusHint:        {1|0}  focus even no-input.
  ignorePagerPreview:       {1|0}  do not show in pager preview.
  ignorePositionHint:       {1|0}  place automatically.
  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 override redirect.
  noFocusOnAppRaise:        {1|0}  no focus on raise.
  noFocusOnMap:             {1|0}  do not focus when mapped.
  noIgnoreTaskBar:          {1|0}  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 which 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 is the example window options file that ships with icewm(1) and typically installs to /usr/share/X11/icewm/winoptions.

```
  # This is an example for IceWM's window options file.
  #
  # Place your variants in /etc/X11/icewm or in $HOME/.icewm
  # since modifications to this file will be discarded when you
  # (re)install icewm.
  xterm.icon: xterm
  rxvt.icon: xterm
  nxterm.icon: xterm
  fte.icon: fte
  emacs.Emacs.icon: emacs
  AWTapp.icon: java
  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
  xeyes.ignoreNoFocusHint: 1
  XClock.ignoreNoFocusHint: 1
  Vim.icon: vim
  applix.ignoreNoFocusHint: 1
  XDdts.noFocusOnAppRaise: 1
  Wingz.noFocusOnAppRaise: 1
  WingzPro.noFocusOnAppRaise: 1
  gkrellm.Gkrellm.allWorkspaces: 1
  gkrellm.Gkrellm.ignoreTaskBar: 1
  gkrellm.Gkrellm.layer: Below
  #gkrellm.Gkrellm.doNotCover: 1
  MainWindow.licq.allWorkspaces: 1
  MainWindow.licq.ignoreQuickSwitch: 1
  MainWindow.licq.ignoreWinList: 1
  MainWindow.licq.layer: Below
  #MainWindow.licq.doNotCover: 1
```

### 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).


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)


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.


incrontab

title: incrontab(5)

text:
# incrontab(5)

## NAME
incrontab - tables for driving inotify cron (incron)

## DESCRIPTION
An incrontab file contains instructions to the incrond(8) daemon of the general form: "run this command on these file events". There are two categories of tables: system tables (with root privileges) and user tables (with user privileges).

System tables are (by default) located in /etc/incron.d and may have any names. Each system table exists separately inside incron and their watches never collide.

Each user has their own table, and commands in any given incrontab will be executed as the user who owns the incrontab. System users (such as apache, postfix, nobody etc.) may have their own incrontab.

incrontab files are read when the incrond(8) daemon starts and after any change (incrontab file are being hooked when incrond is running).

Blank lines are ignored. The general line format is the following:

<path> <mask> <command>

Where path is an absolute filesystem path, mask is an event mask (in symbolic or numeric form) and command is an executable file (or a script) with its arguments. See bellow for event mask symbols. The executable file may be noted as an absolute path or only as the name itself (PATH locations are examined).

Please remember that the same path may occur only once per table (otherwise only the first occurrence takes effect and an error message is emitted to the system log). Please not that the * wildcard is allowed to observe a range of files.

## EVENT SYMBOLS
These basic event mask symbols are defined:

IN_ACCESS File was accessed (read) (*)

IN_ATTRIB Metadata changed (permissions, timestamps, extended attributes, etc.) (*)

IN_CLOSE_WRITE File opened for writing was closed (*)

IN_CLOSE_NOWRITE File not opened for writing was closed (*)

IN_CREATE File/directory created in watched directory (*)

IN_DELETE File/directory deleted from watched directory (*)

IN_DELETE_SELF Watched file/directory was itself deleted

IN_MODIFY File was modified (*)

IN_MOVE_SELF Watched file/directory was itself moved

IN_MOVED_FROM File moved out of watched directory (*)

IN_MOVED_TO File moved into watched directory (*)

IN_OPEN File was opened (*)

When monitoring a directory, the events marked with an asterisk (*) above can occur for files in the directory, in which case the name field in the returned event data identifies the name of the file within the directory.

The IN_ALL_EVENTS symbol is defined as a bit mask of all of the above events. Two additional convenience symbols are IN_MOVE, which is a combination of IN_MOVED_FROM and IN_MOVED_TO, and IN_CLOSE which combines IN_CLOSE_WRITE and IN_CLOSE_NOWRITE.

The following further symbols can be specified in the mask:

IN_DONT_FOLLOW Don't dereference pathname if it is a symbolic link

IN_ONESHOT Monitor pathname for only one event

IN_ONLYDIR Only watch pathname if it is a directory

Additionally, there is a symbol which doesn't appear in the inotify symbol set. It is loopable=true. This symbol disables monitoring events until the current one is completely handled (until its child process exits). Also, there is the symbol recursive=false. This symbol limits the observation on the specified directory and does not include subdirectories. Finally, there is also the symbol dotdirs=true. This symbol will include the hidden directories (where the names starts with a dot) in the observation.

## WILDCARDS
The following wildards may be used inside command specification:

$$ dollar sign

$@ watched filesystem path (see above)

$# event-related file name

$% event flags (textually)

$& event flags (numerically)

## EXAMPLE
These are some example rules which can be used in an incrontab file:

/tmp IN_ALL_EVENTS abcd $@/$# $%

/usr/bin IN_ACCESS,loopable=true abcd $#

/home IN_CREATE /usr/local/bin/abcd $#

/home IN_CREATE,dotdirs=true /usr/local/bin/abcd $#

/home IN_CREATE,recursive=false /usr/local/bin/abcd $#

/var/log 12 abcd $@/$#

The first line monitors all events on the /tmp directory. When an event occurs it runs a application called 'abcd' with the full path of the file as the first arguments and the event flags as the second one.

The second line monitors accesses (readings) on the /usr/bin directory. The application 'abcd' is run as a handler and the appropriate event watch is disabled until the program finishes. The file name (without the directory path) is passed in as an argument.

The third example is used for monitoring the /home directory for newly create files or directories (it practically means an event is sent when a new user is added). This event is processed by a program specified by an absolute path.

The fourth example is the third example, but it will include hidden directories in the observation.

The fifth example is the third example, but it will exclude sub-directories from the observation.

And the final line shows how to use numeric event mask instead of textual one. The value 12 is exactly the same as IN_ATTRIB,IN_CLOSE_WRITE.

## SEE ALSO
incrond(8), incrontab(1), incron.conf(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.


info

package: info

title: info(5)

summary: readable online documentation

text:
# info(5)

## NAME
info - readable online documentation

## DESCRIPTION
The Info file format is an easily-parsable representation for online documents. It can be read by emacs(1) and info(1) among other programs.

Info files are usually created from texinfo(5) sources by makeinfo(1), but can be created from scratch if so desired.

For a full description of the Texinfo language and associated tools, please see the Texinfo manual (written in Texinfo itself). Most likely, running this command from your shell:

```
info texinfo
```

or this key sequence from inside Emacs:

```
M-x info RET m texinfo RET
```

will get you there.

## AVAILABILITY
http://www.gnu.org/software/texinfo/

## REPORTING BUGS
Please send bug reports to bug-texinfo@gnu.org, general questions and discussion to help-texinfo@gnu.org.

## SEE ALSO
info(1), install-info(1), makeinfo(1), texi2dvi(1),

texindex(1).

emacs(1), tex(1).

texinfo(5).


active

package: inn

title: active(5)

text:
# active(5)

## NAME
active - List of newsgroups carried by the server

## DESCRIPTION
The file pathdb/active lists the newsgroups carried by INN. This file is generally maintained using ctlinnd(8) to create and remove groups, or by letting controlchan(8) do so on the basis of received control messages; this file is then updated and a backup stored in pathdb/active.old. Note that the newsgroups(5) file normally contains the descriptions of the newsgroups carried by the news server.

The active file should not be edited directly without throttling innd, and must be reloaded using ctlinnd before innd is unthrottled. Editing it directly even with those precautions may make it inconsistent with the overview database and won't update active.times, so ctlinnd should be used to make modifications whenever possible.

Each newsgroup should be listed only once. Each line specifies one group. The order of groups does not matter. Within each newsgroup, received articles for that group are assigned monotonically increasing numbers as unique names. If an article is posted to newsgroups not mentioned in this file, those newsgroups are ignored.

If none of the newsgroups listed in the Newsgroups: header of an article are present in this file, the article is either rejected (if wanttrash is false in inn.conf), or is filed into the newsgroup "junk" and, when "Aj" is not set in the newsfeeds feed pattern, only propagated to sites that receive the "junk" newsgroup (if wanttrash is true).

Each line of this file consists of four fields separated by a space:

```
    <name> <high> <low> <status>
```

The first field is the name of the newsgroup. The newsgroup "junk" is special, as mentioned above. The newsgroup "control" and any newsgroups beginning with "control." are also special; control messages are filed into a control.* newsgroup named after the type of control message if that group exists, and otherwise are filed into the newsgroup "control" (without regard to what newsgroups are listed in the Newsgroups: header). If mergetogroups is set to true in inn.conf, newsgroups that begin with "to." are also treated specially; see innd(8).

The second field is the highest article number that has been used in that newsgroup. The third field is the lowest article number in the group; this number is not guaranteed to be accurate, and should only be taken to be a hint. It is normally updated nightly as part of the expire process; see news.daily(8) and look for "lowmark" or "renumber" for more details. Note that because of article cancellations, there may be gaps in the numbering sequence. If the lowest article number is greater than the highest article number, then there are no articles in the newsgroup. In order to make it possible to update an entry in-place without rewriting the entire file, the second and third fields are padded out with leading zeros to make them a fixed width.

The fourth field contains one of the following status:

```
    y         Local postings and articles from peers are allowed.
    m         The group is moderated and all postings must be approved.
    n         No local postings are allowed, only articles from peers.
    j         Articles from peers are filed in the junk group instead.
    x         No local postings, and articles from peers are ignored.
    =foo.bar  Articles are filed in the group foo.bar instead.
```

If a newsgroup has the "j" status, no articles will be filed in that newsgroup. Local postings are not accepted; if an article for that newsgroup is received from a remote site, and if it is not crossposted to some other valid group, it will be filed into the "junk" newsgroup instead. This is different than simply not listing the group, since the article will still be accepted and can be propagated to other sites, and the "junk" group can be made available to readers if wished.

If the <status> field begins with an equal sign, the newsgroup is an alias. Articles cannot be posted to that newsgroup, but they can be received from other sites. Any articles received from peers for that newsgroup are treated as if they were actually posted to the group named after the equal sign. Note that the Newsgroups: header of the articles is not modified. (Alias groups are typically used during a transition and are typically created manually with ctlinnd(8).) An alias should not point to another alias.

Note that readers.conf can be configured so that local posts to newsgroups with status "j", "n" or "x" are accepted.

## MINIMAL ACTIVE FILE
For innd to be able to start, the three groups "control", "control.cancel" and "junk" need to be in the active file. Besides, if mergetogroups is set to true in inn.conf, the newsgroup "to" also needs to exist.

The minimal active file shipped with INN is:

```
    control 0000000000 0000000001 n
    control.cancel 0000000000 0000000001 n
    control.checkgroups 0000000000 0000000001 n
    control.newgroup 0000000000 0000000001 n
    control.rmgroup 0000000000 0000000001 n
    junk 0000000000 0000000001 n
```

(Note that the second and the third field may differ if the news server has already been in use.)

There are more control.* pseudogroups here than needed by innd to start; the corresponding control messages will be filed into them. The "n" status is so that users cannot post directly to these groups (control messages should only be posted to the groups that they affect). If you do not want these groups to be visible to clients, do not delete them but simply hide them in readers.conf(5).

To create additional groups after the server is running, you can use "ctlinnd newgroup". You can also synchronize your newsgroup list to that of another server by using actsync(8) or get the active file of another NNTP server with getlist(1). And do not forget to update your newsgroups file, which can be automatically done thanks to docheckgroups called with the -u flag.

## HISTORY
Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. Converted to POD by Russ Allbery <eagle@eyrie.org>.

$Id: active.pod 9767 2014-12-07 21:13:43Z iulius $

## SEE ALSO
active.times(5), actsync(8), controlchan(8), ctlinnd(8), docheckgroups(8), getlist(1), inn.conf(5), innd(8), mod-active(8), news.daily(8), newsgroups(5), readers.conf(5).


active.times

title: active.times(5)

text:
# active.times(5)

## NAME
active.times - List of local creation times of newsgroups

## DESCRIPTION
The file pathdb/active.times provides a chronological record of when newsgroups were created on the local server. This file is normally updated by mod-active and innd whenever a newgroup control message is processed or a "ctlinnd newgroup" command is issued, and is used by nnrpd to answer NEWGROUPS requests.

Each line consists of three fields:

```
    <name> <time> <creator>
```

The first field is the name of the newsgroup. The second field is the time it was created, expressed as the number of seconds since the epoch. The third field is plain text intended to describe the entity that created the newsgroup. This field is encoded in UTF-8 and is usually the e-mail address of the person who created the group, as specified in the control message or on the ctlinnd command line, or the newsmaster specified at configure time if no creator argument was given to ctlinnd (by default, it is "usenet").

You can get the active.times file of another NNTP server with getlist(1).

## EXAMPLE
The line:

```
   news.admin.moderation 1175716803 <group-admin@isc.org>
```

shows that the newsgroup news.admin.moderation was created on April 4th, 2007, at 20:00:03 UTC. This date can be obtained for instance with "convdate -dc 1175716803" (convdate(1) is shipped with INN) or "date -u -d "Jan 1, 1970 00:00:00 +0000 + 1175716803 seconds"". It is when the newsgroup was locally created; in this example, it is when a control message sent by "group-admin@isc.org" was received and processed by the news server (see control.ctl(5) for more details). Therefore, the time is not necessarily the same on every news server.

## HISTORY
Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. Converted to POD by Russ Allbery <eagle@eyrie.org>.

$Id: active.times.pod 9971 2015-12-10 20:30:10Z iulius $

## SEE ALSO
active(5), convdate(1), ctlinnd(8), getlist(1), inn.conf(5), innd(8), mod-active(8), nnrpd(8).


buffindexed.conf

title: buffindexed.conf(5)

text:
# buffindexed.conf(5)

## NAME
buffindexed.conf - Configuration for the buffindexed overview method

## DESCRIPTION
buffindexed.conf, found in pathetc, specifies the buffers that the buffindexed overview method should use. It is required if the server uses buffindexed (as configured by the ovmethod parameter in inn.conf).

Buffindexed uses pre-built buffer files to store overview data and indexes to that data. The buffers are divided into 8 KB internally, and a given block is used either for overview data or for index data. A block is always allocated to a single newsgroup and is never shared among newsgroups.

In addition to the buffers, buffindexed also stores information in a file named group.index in pathdb. (This file should not be mistaken for the one named group.index in pathoverview which is used by the tradindexed overview method.) It contains information about each newsgroup: the pointer to the index block for the newsgroup, the high mark, the low mark, the flag of the group, the number of articles, and so forth. This file is created automatically when all buffers are initialized and should not be manually edited.

Buffindexed buffers are of fixed size, so buffindexed will never use more space than what is available in those buffers. If all buffers are full, innd will throttle when it attempts to store overview information for any additional articles until space is freed (with expireover, for instance) or another buffer is added. This is unlike the CNFS storage method.

You can see the current usage of the buffers with the -o option to inndf.

In the buffindexed.conf file, blank lines and lines beginning with a number sign ("#") are ignored. All other lines must be of the format:

```
    <index>:<filename>:<size>
```

The order of lines is not significant.

<index> is the index of this overview buffer and must be unique. Other than that constraint, it can be any number between 0 and 65535.

<filename> is the path to the buffer. The length of the path should not be longer than 63 characters.

<size> is the length of the buffer in kilobytes (1 KB = 1024 bytes). If <filename> does not specify a special device, the file size of the buffer must be <size> * 1024 bytes. If it does specify a special device, that device must have at least <size> space available. For more information on setting up the buffers, see "CREATING BUFFERS".

An example of buffindexed.conf file can be:

```
    0:<pathoverview in inn.conf>/OV1:1536000
    1:<pathoverview in inn.conf>/OV2:1536000
```

When you first start innd with everything configured properly, you should see messages like this in pathlog/news.notice:

```
    Aug 27 00:00:00 kevlar innd: buffindexed: no magic cookie found
        for ovbuff 0, initializing
```

You MUST recreate overview completely using makehistory if you remove or replace buffers. However, new buffers can be added without any special care (other than restarting innd after modifying buffindexed.conf). If you need to rebuild overview, you should zero all of the buffers first.

We recommend not to reserve too much spare space in existing buffers, so that to minimize the duration of the expireover process, and to just add new buffers when space left is low (see the result of "inndf -no"). Plan on needing at least 0.65 KB for every article in your spool (not counting crossposts). So, if you have 5 million articles, you'll need at least 3.25 GB of disk space for buffindexed.

## CREATING BUFFERS
There are two methods to create a new buffindexed buffer:

1.

Create a large file on top of a regular file system. The easiest way to do this is probably with dd(1), using a command like:

```
    dd if=/dev/zero of=/path/to/cycbuff bs=1024 count=<size>

```

where <size> is the size from the relevant line in buffindexed.conf.

This is the simplest method, but has the disadvantage that very large files on regular file systems can be fairly slow to access, particularly at the end of the file, and INN incurs unnecessary file system overhead when accessing the buffer.

2.

Use block devices directly. If your operating system allows you to call mmap() on block devices (Solaris and recent versions of Linux do, FreeBSD at last report does not), this method can avoid all of the native file system overhead. Note, however, that Solaris has problems with byte range locking on block devices, and therefore this method should not be used on Solaris. Partition the disk. If you're using Solaris, set up your partitions to avoid the first cylinder of the disk (or otherwise the buffindexed header will overwrite the disk partition table and render the buffers inaccessible). Then, create device files for each block device you're going to use.

It's not recommended to use the block device files in /dev, since the news system doesn't have permission to write to them and changing the permissions of the system device files may affect something else. Instead, use mknod(1) to create a new set of block devices (in somewhere like pathspool/overview that's only writable by the news user). To do this, run "ls -Ll" on the devices in /dev that correspond to the block devices that you want to use. The major and minor device numbers are in the fifth and sixth columns (right before the date), respectively. Then run mknod like:

```
    mknod <filename> b <major> <minor>

```

where <filename> is the path to the device to create (matching the <filename> part of the buffindexed configuration line) and <major> and <minor> are the major and minor device numbers as discovered above.

Here's a short script to do this when given the path to the system device file as an argument:

```
    #!/bin/sh
    base=`echo "$1" | sed 's%.*/%%'`
    major=`ls -Ll "$1" | awk '{print $5}' | tr -d ,`
    minor=`ls -Ll "$1" | awk '{print $6}`
    mkdir -p <pathoverview in inn.conf>
    mknod <pathoverview>/"$base" b "$major" "$minor"
    chown news:news <pathoverview>/"$base"
    chmod 644 <pathoverview>/"$base"

```

Make sure that the created files are owned by the news user and news group, as specified at configure time (the default being "news" for both). Also make sure that the permissions on the devices allow the news user to read and write.

## HISTORY
Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews. Converted to POD by Russ Allbery <eagle@eyrie.org>.

$Id: buffindexed.conf.pod 10525 2021-01-20 11:51:15Z iulius $

## SEE ALSO
expireover(8), inn.conf(5), inndf(8), makehistory(8).