swaync

package: swaync

title: swaync(5)

text:
# swaync(5)

## NAME
swaync - Configuration file

## CONFIGURATION
Using a text editor with a JSON language server is recommended when editing the config file to be able to detect config errors

ignore-gtk-theme

type: bool

default: true

description: Unsets the GTK_THEME environment variable, fixing a lot of

issues with GTK themes ruining the users custom CSS themes.

positionX

type: string

default: right

values: left, right, center

description: Horizontal position of control center and notification window

positionY

type: string

default: top

values: top, center, bottom

description: Vertical position of control center and notification window

layer

type: string

default: overlay

values: background, bottom, top, overlay

description: Layer of notification window relative to normal windows.

background is below all windows, overlay is above all windows.

layer-shell

type: bool

default: true

description: Wether or not the windows should be opened as layer-shell

surfaces. Note: Requires swaync restart to apply

cssPriority

type: string

default: application

values: application, user

description: Which GTK priority to use when loading the default and user

CSS files. Pick "user" to override XDG_CONFIG_HOME/gtk-3.0/gtk.css

control-center-positionX

type: string

default: right

values: left, right, center

description: Optional: Horizontal position of the control center.

Supersedes positionX if not set to `none`.

control-center-positionY

type: string

default: top

values: top, center, bottom

description: Optional: Vertical position of the control center.

Supersedes positionY if not set to `none`.

control-center-margin-top

type: integer

default: 0

description: The margin (in pixels) at the top of the notification center. 0 to disable

control-center-margin-bottom

type: integer

default: 0

description: The margin (in pixels) at the bottom of the notification center. 0 to disable

control-center-margin-right

type: integer

default: 0

description: The margin (in pixels) at the right of the notification center. 0 to disable

control-center-margin-left

type: integer

default: 0

description: The margin (in pixels) at the left of the notification center. 0 to disable

control-center-layer

type: string

default: top

values: background, bottom, top, overlay

description: Layer of control center window relative to normal windows.

background is below all windows, overlay is above all windows.

control-center-exclusive-zone

type: bool

default: true

description: Whether or not the control center should follow the

compositors exclusive zones. An example would be setting it to

false to cover your panel/dock.

notification-2fa-action

type: bool

default: true

description: If each notification should display a 'COPY "1234"' action

timeout

type: integer

default: 10

description: The notification timeout for notifications with normal priority

timeout-low

type: integer

default: 5

description: The notification timeout for notifications with low priority

timeout-critical

type: integer

default: 0

description: The notification timeout for notifications with critical priority. 0 to disable

notification-window-width

type: integer

default: 500

description: Width of the notification in pixels

notification-window-height

type: integer

default: -1

description: Max height of the notification in pixels. -1 to use

the full amount of space given by the compositor.

notification-window-preferred-output

type: string

default: ""

description: The preferred output to open the notification window

(popup notifications). Can either be the monitor connector

name (ex: "DP-1"), or the full name, manufacturer model serial

(ex: "Acer Technologies XV272U V 503023B314202").

If the output is not found, the currently focused one is picked.

keyboard-shortcuts

type: bool

default: true

description: If control center should use keyboard shortcuts

notification-grouping

type: bool

default: true

description: If notifications should be grouped by app name

image-visibility

type: string

default: always

values: always, when-available, never

description: An explanation about the purpose of this instance.

transition-time

type: integer

default: 200

description: The notification animation duration. 0 to disable

hide-on-clear

type: bool

default: false

description: Hides the control center after pressing "Clear All"

hide-on-action

type: bool

default: true

description: Hides the control center when clicking on notification action

text-empty

type: string

default: "No Notifications"

description: Text that appears when there are no notifications to show

fit-to-screen

type: bool

default: true

description: Whether the control center should expand vertically to fill the screen

relative-timestamps

type: bool

default: true

description: Display notification timestamps relative to now e.g. "26 minutes ago".

If false, a local iso8601-formatted absolute timestamp is displayed.

control-center-height

type: integer

default: 500

description: Height of the control center in pixels.

A value of -1 means that it will fit to the content.

Ignored when 'fit-to-screen' is set to 'true'.

Also limited to the height of the monitor, unless

control-center-width

type: integer

default: 500

description: The control center width in pixels

control-center-preferred-output

type: string

default: ""

description: The preferred output to open the control center. Can either

be the monitor connector name (ex: "DP-1"), or

the full name, manufacturer model serial

(ex: "Acer Technologies XV272U V 503023B314202"). If the

output is not found, the currently focused one is picked.

notification-action-filter

type: object

visibility object properties:

use-regex

type: bool

optional: true

default: false

description: Indicates if all the below fields should use

regex or not.

app-name

type: string

optional: true

description: The app-name.

desktop-entry

type: string

optional: true

description: The desktop-entry.

id-matcher

type: string

optional: true (needs at least one matcher)

description: Matches the actions identifier. Can be found by

reading the output of swaync when run with the

G_MESSAGES_DEBUG=all environment variable.

text-matcher

type: string

optional: true (needs at least one matcher)

description: Matches the actions text visible in the notification.

description: Hides matching action(s) of matching notifications.

If the notification doesn't include one of the properties, that

property will be ignored. If all properties match the given

notification, the matching actions will be hidden.

example:

```
{
	"notification-action-filter": {
		"hide-chromium-settings": {
			"desktop-entry": "chromium-browser",
			"use-regex": false,
			"id-matcher": "settings",
			"text-matcher": "Settings"
		}
	},
}
```

notification-visibility

type: object

visibility object properties:

state

type: string

optional: false

default: enabled

values: ignored, muted, transient, enabled

description: The notification visibility state.

override-urgency

type: string

optional: true

default: unset

values: unset, low, normal, critical

description: The new urgency for the notification if set.

app-name

type: string

optional: true

description: The app-name. Uses Regex.

desktop-entry

type: string

optional: true

description: The desktop-entry. Uses Regex.

summary

type: string

optional: true

description: The summary of the notification. Uses Regex.

body

type: string

optional: true

description: The body of the notification. Uses Regex.

urgency

type: string

optional: true

default: Normal

values: Low, Normal, Critical

description: The urgency of the notification.

category

type: string

optional: true

description: Which category the notification belongs to. Uses Regex.

description: Set the visibility or override urgency of each incoming

notification.

If the notification doesn't include one of the properties, that

property will be ignored. All properties (except for state) use

regex. If all properties match the given notification, the

notification will be follow the provided state.

Only the first matching object will be used.

example:

```
{
	"notification-visibility": {
		"example-name": {
			"state": "The notification state",
			"app-name": "Notification app-name Regex",
			"summary": "Notification summary Regex",
			"body": "Notification body Regex",
			"urgency": "Low or Normal or Critical",
			"category": "Notification category Regex"
		}
	}
}
```

widgets

type: array

Default values: ["title", "dnd", "notifications"]

Valid array values (see widget-config for more information):

notifications

required: true

optional: false

title

optional: true

dnd

optional: true

label

optional: true

mpris

optional: true

menubar

optional: true

buttons-grid

optional: true

slider

optional: true

volume

optional: true

backlight

optional: true

inhibitors

optional: true

description:

Which order and which widgets to display.

If the "notifications" widget isn't specified, it

will be placed at the bottom.

multiple of same widget:

Append a # with any value to the end of the widget name.

Example: "title#TheMainTitle"

To address this widget specifically in the css file use the css class .TheMainTitle

example:

```
{
	"widgets": [
		"inhibitors",
		"title",
		"dnd",
		"notifications"
	]
}
```

widget-config

type: object

description: Configure specific widget properties.

multiple of same widget:

Append a # with any value to the end of the widget name.

Example: "title#TheMainTitle"

To address this widget specifically in the css file use the css class .TheMainTitle

Widgets to customize:

notifications

type: object

css class: widget-notifications

properties:

vexpand:

type: bool

optional: true

default: true

description: Whether or not the notifications widget

should vertically expand or not

description: The Notifications Widget.

title

type: object

css class: widget-title

properties:

text:

type: string

optional: true

default: "Notifications"

description: The title of the widget

clear-all-button:

type: bool

optional: true

default: true

description: Whether to display a "Clear All" button

button-text:

type: string

optional: true

default: "Clear All"

description: "Clear All" button text

description: The notification visibility state.

dnd

type: object

css class: widget-dnd

properties:

text:

type: string

optional: true

default: "Do Not Disturb"

description: The title of the widget

description: Control Center Do Not Disturb Widget.

label

type: object

css class: widget-label

properties:

text:

type: string

optional: true

default: "Label Text"

description: The text content of the widget

clear-all-button:

type: integer

optional: true

default: 5

description: The maximum lines

description: A generic widget that allows the user to add custom text.

mpris

type: object

css classes:

widget-mpris

widget-mpris-player

widget-mpris-title

widget-mpris-subtitle

properties:

blacklist:

type: array

optional: true

default: []

description: Audio sources for the mpris widget to ignore.

Valid array values:

type: string

description: Audio source/app name. Regex allowed. Hint

`$ qdbus | grep mpris` to find source names.

autohide:

type: bool

optional: true

default: false

description: Whether to hide the widget when the

player has no metadata.

show-album-art:

type: string

optional: true

default: "always"

description: Whether or not the album art should be

hidden, always visible, or only visible

when a valid album art is provided.

enum: ["right", "left"]

loop-carousel:

type: bool

optional: true

default: false

description: Whether to loop through the mpris carousel.

description: A widget that displays multiple music players.

menubar

type: object

css classes:

widget-menubar

name of element given after menu or buttons with #

patternProperties:

menu#<name>:

type: object

properties:

label:

type: string

optional: true

default: "Menu"

description: Label of button to show/hide menu dropdown

position:

type: string

optional: true

default: "right"

description: Horizontal position of the button in the bar

enum: ["right", "left"]

animation-type:

type: string

optional: true

default: "slide_down"

description: Animation type for menu

enum: ["slide_down", "slide_up", "none"]

animation-duration:

type: integer

optional: true

default: 250

description: Duration of animation in milliseconds

actions:

type: array

Default values: []

Valid array values:

type: object

properties:

label:

type: string

default: "label"

description: Text to be displayed in button

command:

type: string

default: ""

description: "Command to be executed on click"

type:

type: string

default: "normal"

description: Type of the button.

Toggle buttons receive the '.active' css class

enum: ["normal", "toggle"]

update-command:

type: string

default: ""

description: "Command to be executed on visibility change of

cc to update the active state of the toggle button (should

echo true or false)"

active:

type: bool

default: false

description: Wether the toggle button is active as default or not

description: A list of actions containing a label and a command

description: A button to reveal a dropdown with action-buttons

buttons#<name>:

type: object

properties:

position:

type: string

optional: true

default: "right"

description: Horizontal position of the buttons in the bar

enum: ["right", "left"]

actions:

type: array

Default values: []

Valid array values:

type: object

properties:

label:

type: string

default: "label"

description: Text to be displayed in button

command:

type: string

default: ""

description: "Command to be executed on click"

type:

type: string

default: "normal"

description: Type of the button

Toggle buttons receive the '.active' css class and an env

variable "SWAYNC_TOGGLE_STATE" is set. See example usage in the

default config.json

enum: ["normal", "toggle"]

update-command:

type: string

default: ""

description: "Command to be executed on visibility change of

cc to update the active state of the toggle button (should

echo true or false)"

active:

type: bool

default: false

description: Wether the toggle button is active as default or not

description: A list of actions containing a label and a command

description: A list of buttons to be displayed in the menu-button-bar

buttons-grid

type: object

css class: widget-buttons (access buttons with >flowbox>flowboxchild>button)

properties:

buttons-per-row:

type: number

actions:

type: array

Default values: []

Valid array values:

type: object

properties:

label:

type: string

default: "label"

description: Text to be displayed in button

command:

type: string

default: ""

description: "Command to be executed on click"

type:

type: string

default: "normal"

description: Type of the button

Toggle buttons receive the '.active' css class and an env

variable "SWAYNC_TOGGLE_STATE" is set. See example usage in the

default config.json

enum: ["normal", "toggle"]

active:

type: bool

default: false

description: Wether the toggle button is active as default or not

description: A list of actions containing a label and a command

description: A grid of buttons that execute shell commands

slider

type: object

css class: widget-slider

properties:

label:

type: string

optional: true

default: "slider"

description: Text displayed in front of the slider

cmd_setter:

type: string

optional: true

default: ""

description: command to set the value. Use $value to get

the current value.

cmd_getter:

type: string

optional: true

default: ""

description: command to get the actual value.

Use $value to get the current value.

min:

type: integer

optional: true

default: 0

description: minimum value of the slider range

max:

type: integer

optional: true

default: 100

description: maximum value of the slider range

min_limit:

type: integer

optional: true

default: 0

description: limit minimum value of the slider

max_limit:

type: integer

optional: true

default: 100

description: limit maximum value of the slider

value_scale:

type: integer

optional: true

default: 0

description: scale small value, slider round digits

description: general slider control

volume

type: object

css class:

widget-volume

per-app-volume

properties:

label:

type: string

optional: true

default: "Volume"

description: Text displayed in front of the volume slider

show-per-app:

type: bool

optional: true

default: false

description: Show per app volume control

show-per-app-icon:

type: bool

optional: true

default: false

description: Show application icon in per app control

show-per-app-label:

type: bool

optional: true

default: false

description: Show application name in per app control

expand-per-app:

type: bool

optional: true

default: false

description: If the per app section should start expanded

empty-list-label:

type: string

optional: true

default: "No active sink input"

description: Text displayed when there are not active sink inputs

expand-button-label:

type: string

optional: true

default: "⇧"

description: Label displayed on button to show per app volume control

collapse-button-label:

type: string

optional: true

default: "⇩"

description: Label displayed on button to hide per app volume control

animation-type:

type: string

optional: true

default: "slide_down"

description: Animation type for the per app volume control

enum: ["slide_down", "slide_up", "none"]

animation-duration:

type: integer

optional: true

default: 250

description: Duration of animation in milliseconds

description: Slider to control pulse volume

backlight

type: object

css class: widget-backlight

properties:

label:

type: string

optional: true

default: "Brightness"

description: Text displayed in front of the backlight slider

device:

type: string

optional: true

default: "intel_backlight"

description: Device in `/sys/class/backlight` or `/sys/class/leds`

subsystem:

type: string

optional: true

default: "backlight"

description: Kernel subsystem for brightness control

enum: ["backlight", "leds"]

min:

type: integer

optional: true

default: 0

description: Lowest possible value for brightness

description: Slider to control screen brightness

inhibitors

type: object

css class: widget-inhibitors

properties:

text:

type: string

optional: true

default: "Inhibitors"

description: The title of the widget

clear-all-button:

type: bool

optional: true

default: true

description: Whether to display a "Clear All" button

button-text:

type: string

optional: true

default: "Clear All"

description: "Clear All" button text

description: Displayed if notifications are inhibited.

example:

```
{
	"widget-config": {
		"title": {
			"text": "Notifications",
			"clear-all-button": true,
			"button-text": "Clear All"
		},
		"dnd": {
			"text": "Do Not Disturb"
		},
		"label": {
			"max-lines": 5,
			"text": "Label Text"
		},
		"mpris": {
			"blacklist": ["playerctld"],
			"autohide": true,
			"show-album-art": "always",
			"loop-carousel": false
		},
		"menubar": {
			"menu#power": {
				"label": "Power",
				"position": "right",
				"actions": [
					{
						"label": "Shut down",
						"command": "systemctl poweroff"
					},
					...
				]
			},
			"buttons#screenshot": {
				"position": "left",
				"actions": [
					{
						"label": "Screenshot",
						"command": "grim"
					},
					...
				]
			}
		},
		"buttons": {
			"actions": [
				{
					"label": "wifi",
					"command": "rofi-wifi-menu"
				},
				...
			]
		}
	}
}
```

## Scripts
script-fail-notify

type: bool

default: true

description: Sends a notification if a script fails to run

scripts

type: object

script object properties:

exec

type: string

optional: false

description: The script to run. Can also run regular shell commands.

app-name

type: string

optional: true

description: The app-name. Uses Regex.

desktop-entry

type: string

optional: true

description: The desktop-entry. Uses Regex.

summary

type: string

optional: true

description: The summary of the notification. Uses Regex.

body

type: string

optional: true

description: The body of the notification. Uses Regex.

urgency

type: string

optional: true

default: Normal

values: Low, Normal, Critical

description: The urgency of the notification.

category

type: string

optional: true

description: Which category the notification belongs to. Uses Regex.

sound-file

type: string

optional: true

description: Which sound file the notification requested. Uses Regex.

sound-name

type: string

optional: true

description: Which sound name the notification requested. Uses Regex.

run-on

type: string

optional: true

values: action, receive

default: receive

description: Whether to run this action when the notification is

received, or when an action is taken on it.

description: Which scripts to check and potentially run for every

notification. If the notification doesn't include one of the properties,

that property will be ignored. All properties (except for exec) use regex.

If all properties match the given notification, the script will be run.

Only the first matching script will be run.

example:

```
{
	"scripts": {
		"example-script": {
			"exec": "Your shell command or script here...",
			"app-name": "Notification app-name Regex",
			"summary": "Notification summary Regex",
			"body": "Notification body Regex",
			"urgency": "Low or Normal or Critical",
			"category": "Notification category Regex"
		}
	}
}
```

You can also use these environment variables in your script:

```
$SWAYNC_BODY="Notification body content"
$SWAYNC_DESKTOP_ENTRY="Desktop entry"
$SWAYNC_URGENCY="Notification urgency"
$SWAYNC_TIME="Notification time"
$SWAYNC_APP_NAME="Notification app name"
$SWAYNC_CATEGORY="SwayNC notification category"
$SWAYNC_REPLACES_ID="ID of notification to replace"
$SWAYNC_ID="SwayNC notification ID"
$SWAYNC_SUMMARY="Notification summary"
$SWAYNC_HINT_[NAME]="Value of the hint [NAME]"
$SWAYNC_SOUND_NAME="The name of the requested sound"
$SWAYNC_SOUND_FILE="The file path of the requested sound"
```


swtpm-localca.conf

package: swtpm-tools

title: swtpm-localca.conf(5)

summary: Configuration file for swtpm_localca

text:
# swtpm-localca.conf(5)

## NAME
swtpm-localca.conf - Configuration file for swtpm_localca

## DESCRIPTION
The file /etc/swtpm-localca.conf contains configuration variables for the swtpm_localca program.

Entries may contain environment variables that will be resolved. All environment variables must be formatted like this: '${varname}'.

Users may write their own configuration into ${XDG_CONFIG_HOME}/swtpm-localca.conf or if XDG_CONFIG_HOME is not set it may be in ${HOME}/.config/swtpm-localca.conf.

The following configuration variables are supported:

statedir

The name of a directory where to store data into. A lock will be created in this directory.

signinkey

The file containing the key used for signing the certificates. Provide a key in PEM format or a pkcs11 URI.

signingkey_password

The password to use for the signing key.

issuercert

The file containing the certificate for this CA. Provide a certificate in PEM format.

certserial

The name of file containing the serial number for the next certificate. The serial number must be a decimal number and must be representable with 20 bytes or less. Once 21 bytes are used a new random serial number with 20 decimal digits will be created.

TSS_TCSD_HOSTNAME

This variable can be set to the host where tcsd is running on in case the signing key is a GnuTLS TPM 1.2 key. By default localhost will be used.

TSS_TCSD_PORT

This variable can be set to the port on which tcsd is listening for connections. By default port 30003 will be used.

env:<environment variable name=<value>>

Environment variables, that are needed by pkcs11 modules, can be set using this format. An example for such an environment variable may look like this:

```
    env:MY_MODULE_PKCS11_CONFIG = /tmp/mymodule-pkcs11.conf

```

The line must not contain any trailing spaces.

## EXAMPLE
An example swtpm-localca.conf file may look as follows:

```
 statedir = /var/lib/swtpm_localca
 signingkey = /var/lib/swtpm_localca/signkey.pem
 issuercert = /var/lib/swtpm_localca/issuercert.pem
 certserial = /var/lib/swtpm_localca/certserial
```

With a PKCS11 URI it may look like this:

```
 statedir = /var/lib/swtpm-localca
 signingkey = pkcs11:model=SoftHSM%20v2;manufacturer=SoftHSM%20project;serial=891b99c169e41301;token=mylabel;id=%00;object=mykey;type=public
 issuercert = /var/lib/swtpm-localca/swtpm-localca-tpmca-cert.pem
 certserial = /var/lib/swtpm-localca/certserial
 SWTPM_PKCS11_PIN = 1234
```

## SEE ALSO
swtpm_localca

## REPORTING BUGS
Report bugs to Stefan Berger <stefanb@linux.vnet.ibm.com>

branch: sisyphus


swtpm-localca.options

title: swtpm-localca.options(5)

summary: Options file for swtpm_localca

text:
# swtpm-localca.options(5)

## NAME
swtpm-localca.options - Options file for swtpm_localca

## DESCRIPTION
The file /etc/swtpm-localca.options contains command line options to pass to the swtpm_cert program and should hold options that apply to the creation of all TPM Endorsement Key (EK) and platform certificates.

Users may write their own options into ${XDG_CONFIG_HOME}/swtpm-localca.options or if XDG_CONFIG_HOME is not set it may be in ${HOME}/.config/swtpm-localca.options.

## EXAMPLE
An example swtpm-localca.options file may look as follows:

```
  --platform-manufacturer Fedora
  --platform-version 2.1
  --platform-model QEMU
```

## SEE ALSO
swtpm_localca

## REPORTING BUGS
Report bugs to Stefan Berger <stefanb@linux.vnet.ibm.com>


title: swtpm_setup.conf(5)

summary: Configuration file for swtpm_setup

text:
# swtpm_setup.conf(5)

## NAME
swtpm_setup.conf - Configuration file for swtpm_setup

## DESCRIPTION
The file /etc/swtpm_setup.conf contains configuration information for swtpm_setup. It must only contain one configuration keyword per line, followed by an equals sign (=) and then followed by appropriate configuration information. A comment at the end of the line may be introduced by a hash (#) sign.

Users may write their own configuration into ${XDG_CONFIG_HOME}/swtpm_setup.conf or if XDG_CONFIG_HOME is not set it may be in ${HOME}/.config/swtpm_setup.conf.

The following keywords are recognized:

create_certs_tool

This keyword is to be followed by the name of an executable or executable script used for creating various TPM certificates. The tool will be called with the following options

--type type

This parameter indicates the type of certificate to create. The type parameter may be one of the following: ek, or platform

--dir dir

This parameter indicates the directory into which the certificate is to be stored. It is expected that the EK certificate is stored in this directory under the name ek.cert and the platform certificate under the name platform.cert.

--ek ek

This parameter indicates the modulus of the public key of the endorsement key (EK). The public key is provided as a sequence of ASCII hex digits.

--vmid ID

This parameter indicates the ID of the VM for which to create the certificate.

--logfile <logfile>

The log file to log output to; by default logging goes to stdout and stderr on the console.

--configfile <configuration file>

The configuration file to use. This file typically contains configuration information for the invoked program. If omitted, the program must use its default configuration file.

--optsfile <options file>

The options file to use. This file typically contains options that the invoked program uses. If omitted, the program must use its default options file.

--tpm-spec-family <family>, --tpm-spec-level <level>, --tpm-spec-revision <revision>

These 3 options describe the TPM specification that was followed for the implementation of the TPM and will be part of the EK certificate.

--tpm2

This option is passed in case a TPM 2 compliant certificate needs to be created.

create_certs_tool_config

This keyword is to be followed by the name of a configuration file that will be passed to the invoked program using the --configfile option described above. If omitted, the invoked program will use the default configuration file.

create_certs_tool_options

This keyword is to be followed by the name of an options file that will be passed to the invoked program using the --optsfile option described above. If omitted, the invoked program will use the default options file.

active_pcr_banks (since v0.7)

This keyword is to be followed by a comma-separated list of names of PCR banks. The list must not contain any spaces. Valid PCR bank names are sha1, sha256, sha384, and sha512.

rsa_keysize (since v0.10)

This keyword allows to specify the default RSA keysize to be used if it is not provided with a command line option to swtpm_setup. Any value that can be passed to swtpm_setup is also valid here, such as 2048, or 'max'. The supported key sizes depend on the version of libtpms.

profile (since v0.10)

This keyword allows to specify either the name of a profile or a JSON map describing the profile, such as 'profile = {"Name": "default-v1"}'. Please also refer to the description of the --profile option for swtpm_setup.

profile_file (since v0.10)

This keyword allows to specify a default profile file.

local_profiles_dir (since v0.10)

This keyword allows to set a profile directory that contains profiles written by users of the system.

## SEE ALSO
swtpm_setup

## REPORTING BUGS
Report bugs to Stefan Berger <stefanb@linux.vnet.ibm.com>


auth.conf

package: sympa

title: auth.conf(5)

text:
# auth.conf(5)

## NAME
auth.conf - Configuration of authentication mechanisms for web interface of Sympa

## DESCRIPTION
The auth.conf configuration file defines authentication mechanisms for web interface of Sympa.

### auth.conf structure
Each paragraph starts with one of the names "user_table", "ldap", "generic_sso", "cas" or "cgi".

The auth.conf file contains directives in the following format:

```
  name
  keyword value
  keyword value
  ...

  name
  keyword value
  keyword value
  ...
```

Comments start with the "#" character at the beginning of a line.

Empty lines are also considered as comments and are ignored at the beginning. After the first paragraph, they are considered as paragraph separators. There should only be one directive per line, but their order in the paragraph is of no importance.

Succeeding subsections describe available parameters in each paragraph.

### "user_table" paragraph
This paragraph is related to Sympa internal authentication by email and password. Information of users are stored in "user_table" database table. This is the simplest one.

"regexp" regexp

"negative_regexp"

Perl regular expressions applied on an email address provided, to select or block this authentication mechanism for a subset of email addresses.

### "ldap" paragraph
This paragraph allows one to login to Sympa using data taken from an LDAP directory. Login is done in two steps:

- User provide a user ID or an email address, with a password. These are used to retrieve their distinguished name (DN) in the LDAP directory.

- The email attribute is extracted from the directory entry corresponding to the found DN.

Here is how to configure the LDAP authentication:

"regexp"

"negative_regexp"

Same as in the "user_table" paragraph: If an email address is provided (this does not apply to the user ID), then the regular expression will be applied to find out if the LDAP directory can be used to authenticate a subset of users.

"host"

This keyword is mandatory. It is the domain name used in order to bind to the directory and then to extract information. You must mention the port number after the server name. Server replication is supported by listing several servers separated by commas (","). Example:

```
  host ldap.univ-rennes1.fr:389
  host ldap0.university.com:389,ldap1.university.com:389,ldap2.university.com:389

```

"timeout"

It corresponds to the time limit in the search operation. A "timelimit" that restricts the maximum time (in seconds) allowed for a search. A value of 0 (the default) means that no time limit will be requested.

"suffix"

The root of the DIT (directory information tree). The DN that is the base object entry relative to which the search is to be performed. Example:

```
  dc=university,dc=fr

```

"bind_dn"

If anonymous bind is not allowed on the LDAP server, a DN and password can be used.

"bind_password"

This password is used, combined with the "bind_dn" above.

"get_dn_by_uid_filter"

Defines the search filter corresponding to the "ldap_uid". (RFC 2254 compliant). If you want to apply the filter on the user, use the variable "[sender]". It will work with every type of authentication (user ID, "alternate_email", ...). Example:

```
  (Login = [sender])
  (|(ID = [sender])(UID = [sender]))

```

"get_dn_by_email_filter"

Defines the search filter corresponding to the email addresses (canonic and alternative --- this is RFC 2254 compliant). If you want to apply the filter on the user, use the variable "[sender]". It will work with every type of authentication (user ID, "alternate_email"..). Example: a person is described by

```
  dn: cn=Fabrice Rafart, ou=Siege, o=MaSociete, c=FR
  objectClass: person
  cn: Fabrice Rafart
  title: Network Responsible
  o: Siege
  ou: Data processing
  telephoneNumber: 01-00-00-00-00
  facsimileTelephoneNumber: 01-00-00-00-00
  l: Paris
  country: France
  uid: frafart
  mail: Fabrice.Rafart@MaSociete.fr
  alternate_email: frafart@MaSociete.fr
  alternate: rafart@MaSociete.fr

```

The filters can be:

```
  (mail = [sender])
  (| (mail = [sender])(alternate_email = [sender]) )
  (| (mail = [sender])(alternate_email = [sender])(alternate  = [sender]) )

```

"email_attribute"

The name of the attribute for the canonic email in your directory: for instance "mail", "canonic_email", "canonic_address", ... In the previous example, the canonic email is "mail".

"alternative_email_attribute"

Obsoleted. On Sympa 6.2.38 or earlier, web interface provided a cookie named "sympa_altemails" which contained attribute values specified by this parameter along with authenticated email address. This feature was deprecated.

"scope"

Default value: "sub" By default, the search is performed on the whole tree below the specified base object. This may be changed by specifying a scope:

"base"

Search only the base object,

"one"

Search the entries immediately below the base object,

"sub"

Search the whole tree below the base object. This is the default.

"deref"

Default value: "find" Specifies how to dereference aliases.

Introduced on Sympa 6.2.74.

"never"

Aliases are never dereferenced.

"search"

Aliases are dereferenced in searching subordinates of the base object.

"find"

Aliases are derefernced in locating the base object, but not in searching subordinates of the base object. This is the default.

"always"

Aliases are always dereferenced.

"authentication_info_url"

Defines the URL of a document describing LDAP password management. When hitting Sympa's "Send me a password" button, LDAP users will be redirected to this URL.

TLS parameters

Following parameters are used to provide LDAPS (LDAP over TLS/SSL):

"use_ssl" (OBSOLETE)

If set to 1, connection to the LDAP server will use LDAPS (LDAP over TLS/SSL). Obsoleted as of Sympa 6.2.15. Use "use_tls" instead.

"use_tls"

Default value: "none"

"ldaps"

Use LDAPS (LDAP over TLS/SSL),

"starttls"

Use StartTLS,

"none"

TLS (SSL) is disabled.

"ssl_version"

Default value: "tlsv1" This defines the version of the TLS/SSL protocol to use. Possible values are "sslv2", "sslv3", "tlsv1", "tlsv1_1" and "tlsv1_2".

"ssl_ciphers"

Specify which subset of cipher suites are permissible for this connection, using the standard OpenSSL string format. The default value of Net::LDAPS for ciphers is "ALL", which permits all ciphers, even those that do not encrypt!

"ssl_cert"

Path to client certificate. Introduced on Sympa 6.2.

"ssl_key"

Path to the secret key of client certificate. Introduced on Sympa 6.2.

"ca_verify"

"none", "optional" or "required". If set to "none", will never verify server certificate. Latter two need appropriate "ca_path" and/or "ca_file" settings. Introduced on Sympa 6.2.

"ca_path"

Path to directory store of CA certificates. Introduced on Sympa 6.2.

"ca_file"

Path to file store of CA certificates. Introduced on Sympa 6.2.

### "generic_sso" paragraph
"service_name"

This is the SSO service name that will be offered to the user in the login banner menu.

"service_id"

This service ID is used as a parameter by Sympa to refer to the SSO service (instead of the service name). A corresponding URL on the local web server should be protected by the SSO system; this URL would look like "http://yourhost.yourdomain/sympa/sso_login/inqueue" if the "service_id" is ""inqueue"".

"http_header_list"

Sympa gets user attributes from environment variables coming from the web server. These variables are then cached in the "user_table" database table for later use in authorization scenarios (in structure). You can define a comma-separated list of header field names.

"http_header_prefix"

Only environment variables starting with the defined prefix will be kept. Another option is to list HTTP header fields explicitly using "http_header_list" parameter.

"email_http_header"

This parameter defines the environment variable that will contain the authenticated user's email address.

"http_header_value_separator"

Default: ";" User attributes may be multi-valued (including the user email address. This parameter defines the values separator character(s).

"logout_url"

This optional parameter allows one to specify the SSO logout URL. If defined, Sympa will redirect the user to this URL after the Sympa logout has been performed.

netID mapping parameters

The following parameters define how Sympa can check the user email address, either provided by the SSO or by the user themselves:

"internal_email_by_netid"

If set to 1, this parameter makes Sympa use its "netidmap" table to associate net IDs to user email addresses.

"netid_http_header"

This parameter defines the environment variable that will contain the user's identifier. This net ID will then be associated with an email address provided by the user.

"force_email_verify"

If set to 1, this parameter makes Sympa check the user's email address. If the email address was not provided by the authentication module, then the user is requested to provide a valid email address.

LDAP parameters for generic SSO

The following parameters define how Sympa can retrieve the user email address; these are useful only in case the "email_http_header" entry was not defined:

"host"

(formerly "ldap_host") The LDAP host Sympa will connect to fetch user email. The "host" include the port number and it may be a comma separated list of redundant hosts.

"bind_dn"

(formerly "ldap_bind_dn") The DN used to bind to this server. Anonymous bind is used if this parameter is not defined.

"bind_password"

(formerly "ldap_bind_password") The password used unless anonymous bind is used.

"suffix"

(formerly "ldap_suffix") The LDAP suffix used when searching user email.

"scope"

(formerly "ldap_scope") The scope used when searching user email. Possible values are "sub", "base" and "one".

"deref"

(introduced on 6.2.74) How to dereference the aliases on searching LDAP. Possible values are "never", "search", "find" and "always".

"get_email_by_uid_filter"

(formerly "ldap_get_email_by_uid_filter") The filter used to perform the email search. It can refer to any environment variables inherited from the SSO module, as shown below.

Example:

```
  ldap_get_email_by_uid_filter (mail=[SSL_CLIENT_S_DN_Email])

```

"email_attribute"

(formerly "ldap_email_attribute") The attribute name to be used as user canonical email. In the current version of Sympa, only the first value returned by the LDAP server is used.

"timeout"

(formerly "ldap_timeout") The time out for the search.

TLS parameters

To support LDAPS (LDAP over SSL/TLS), corresponding parameters in "ldap" paragraph may also be used for "generic_sso".

### "cas" paragraph
Note that Sympa will act as a CAS client to validate CAS tickets. During this exchange, Sympa will check the CAS server X.509 certificate. Therefore you should ensure that the certificate authority of the CAS server is known by Sympa ; this should be configured through the cafile or "capath" sympa.conf configuration parameter.

"auth_service_name"

The authentication service name. Note that it is used as an identifier in the code; it should therefore be made of alphanumeric characters only, with no space.

"auth_service_friendly_name"

If defined, this string is proposed on the web login banner.

"host" (OBSOLETE)

This parameter has been replaced by "base_url" parameter.

"base_url"

The base URL of the CAS server.

"non_blocking_redirection"

"on" or "off". Default value: "on" This parameter only concerns the first access to Sympa services by a user, it activates or not the non blocking redirection to the related CAS server to check automatically if the user as been previously authenticated with this CAS server. The redirection to CAS is used with the CGI parameter "gateway=1" that specifies to CAS server to always redirect the user to the original URL, but just check if the user is logged. If active, the SSO service is effective and transparent, but in case the CAS server is out of order, the access to Sympa services is impossible.

"login_uri" (OBSOLETE)

This parameter has been replaced by the "login_path" parameter.

"login_path" (OPTIONAL)

The login service path.

"check_uri" (OBSOLETE)

This parameter has been replaced by the "service_validate_path" parameter.

"service_validate_path" (OPTIONAL)

The ticket validation service path.

"logout_uri" (OBSOLETE)

This parameter has been replaced by the "logout_path" parameter.

"logout_path" (OPTIONAL)

The logout service path.

"proxy_path" (OPTIONAL)

The proxy service path, only used by the Sympa SOAP server.

"proxy_validate_path" (OPTIONAL)

The proxy validate service path, only used by the Sympa SOAP server.

LDAP parameters for CAS

"host"

(formerly "ldap_host") The LDAP host Sympa will connect to fetch user email when user uid is return by CAS service. The "ldap_host" includes the port number and it may be a comma separated list of redundant hosts.

"bind_dn"

(formerly "ldap_bind_dn") The DN used to bind to this server. Anonymous bind is used if this parameter is not defined.

"bind_password"

(formerly "ldap_bind_password") The password used unless anonymous bind is used.

"suffix"

(formerly "ldap_suffix") The LDAP suffix used when searching user email.

"scope"

(formerly "ldap_scope") The scope used when searching user email. Possible values are "sub", "base" and "one".

"deref"

(introduced on 6.2.74) How to dereference the aliases on searching LDAP.

"get_email_by_uid_filter"

(formerly "ldap_get_email_by_uid_filter") The filter used to perform the email search.

"email_attribute"

(formerly "ldap_email_attribute") The attribute name to be used as user canonical email. In the current version of Sympa, only the first value returned by the LDAP server is used.

"timeout"

(formerly "ldap_timeout") The time out for the search.

TLS parameters

To support LDAPS (LDAP over SSL/TLS), corresponding parameters in ldap paragraph may also be used for cas.

### "cgi" paragraph
This paragraph allows Sympa to receive authentication information from the external authentication mechanism through Common Gateway Interface (CGI). By this, Sympa may use authentication methods not supported by Sympa itself.

"regexp"

"negative_regexp"

See "user_table" paragraph.

"remote_user_variable"

The name of the CGI environment variable that contains the e-mail address of the authenticated user. Note that the name of CGI variable is case-sensitive.

"auth_scheme"

Optional. If set, authentication is considered successful only if it matches the name of authentication scheme, i.e. value of the "AUTH_TYPE" CGI environment variable. The value of this parameter is case-insensitive.

## FILES
$DEFAULTDIR/auth.conf

Distribution default. This file should not be edited.

$SYSCONFDIR/auth.conf

$SYSCONFDIR/<robot name>/auth.conf

Configuration files for site-wide default and each robot.

## SEE ALSO
wwsympa(8), sympa_soap_server(8).

Sympa::Auth.

## HISTORY
Descriptions of parameters were originally taken from the chapter "Authentication" in Sympa, Mailing List Management Software - Reference manual, written by Serge Aumont, Soji Ikeda, Olivier Salaün and David Verdin.

"cgi" paragraph was introduced on Sympa 6.2.71b.


title: automatic_lists_description.conf(5)

text:
# automatic_lists_description.conf(5)

## NAME
automatic_lists_description.conf - Description of automatic list creation with web interface

## DESCRIPTION
automatic_lists_description.conf defines criteria to create automatic lists with web interface.

TBD.

## FILES
$SYSCONFDIR/families/<family name>/automatic_lists_description.conf

$SYSCONFDIR/<robot name>/families/<family name>/automatic_lists_description.conf

Files describing a family for site-wide default and each robot.

## SEE ALSO
wwsympa(8), Sympa::Family.

## HISTORY
This document was initially written by IKEDA Soji <ikeda@conversion.co.jp>.


charset.conf

title: charset.conf(5)

text:
# charset.conf(5)

## NAME
charset.conf - Configuration file for legacy character set support by Sympa

## DESCRIPTION
In some language environments, legacy encoding (character set) is preferred for e-mail messages: For example "iso-2022-jp" in Japanese language.

charset.conf defines mapping between language context and legacy character set for service messages sent by Sympa. If you want to enable legacy character set support, simply copy sample charset.conf onto configuration directory:

```
    # cp $DEFAULTDIR/charset.conf $SYSCONFDIR/charset.conf
```

And set the "legacy_character_support_feature" parameter value in sympa.conf to "on".

### Note
If you are planning to upgrade Sympa earlier than 5.3a.8, original charset.conf is required to convert shared documents during upgrade process.

## FILES
$DEFAULTDIR/charset.conf

Distribution default. This file should not be edited.

$SYSCONFDIR/charset.conf

Configuration file.

## SEE ALSO
sympa_config(5).

## HISTORY
Legacy character set support appeared on Sympa 6.0.

This document was initially written by IKEDA Soji <ikeda@conversion.co.jp> at 16, Mar 2009, and modified by VERDIN David <david.verdin@cru.fr> at 27, April 2009.


title: edit_list.conf(5)

text:
# edit_list.conf(5)

## NAME
edit_list.conf - Configuration of privileges to edit list configuration

## DESCRIPTION
edit_list.conf defines privileges to edit list configuration.

$SYSCONFDIR/edit_list.conf is main configuration. Several parameters defined in this file may be overridden by $SYSCONFDIR/<mail domain name>/edit_list.conf file for each mail domain, or by <list config directory>/edit_list.conf file for each mailing list.

Format of edit_list.conf is as following:

- Lines beginning with "#" and containing only spaces are ignored.

- Each line has the form "parameter name role privilege".

parameter name is a list parameter name (e.g. "max_size"), paragraph name ("owner") or subparameter ("owner.email)"). It may be a name of template (e.g. "welcome.tt2") or list configuration file ("message.header") except main configuration file ("config").

role is any of "listmaster", "privileged_owner", "owner" or "editor". Multiple roles have to be separated by comma ("","").

privilege is "write", "read" or "hidden".

Lines are checked in order, then matched line at the first time wins. Default privilege may be specified with special parameter name "default".

## FILES
$DEFAULTDIR/edit_list.conf

Distribution default. This file should not be edited.

$SYSCONFDIR/edit_list.conf

$SYSCONFDIR/<mail domain name>/edit_list.conf

$EXPLDIR/<list name>/edit_list.conf or $EXPLDIR/<mail domain name>/<list name>/edit_list.conf

Configuration files for site-wide default, by each domain or each list.

## SEE ALSO
wwsympa(8).

## HISTORY
This document was initially written by IKEDA Soji <ikeda@conversion.co.jp>.


title: ldap_alias_manager.conf(5)

summary: Configuration of LDAP alias management

text:
# ldap_alias_manager.conf(5)

## NAME
ldap_alias_manager.conf - Configuration of LDAP alias management

## DESCRIPTION
ldap_alias_manager.conf is used by the ldap_alias_manager(8); it allows one to manage mail aliases in an LDAP directory. To make sympa use the ldap_alias_manager.pl script, you should edit the "alias_manager" sympa.conf parameter.

Format of ldap_alias_manager.conf is as following:

- Lines beginning with "#" and containing only spaces are ignored.

- Each line has the form "parameter value". value may contain spaces but may not contain newlines.

### Parameters
ldap_host <host>

Mandatory. LDAP server host. Example:

ldap_host ldap.example.com

ldap_bind_dn <distinguished name>

Mandatory. LDAP bind DN. Example:

ldap_bind_dn cn=sympa,ou=services,dc=example,dc=com

ldap_bind_pwd <secret>

Mandatory. LDAP bind password. Example:

ldap_bind_pwd secret

ldap_base_dn <distinguished name>

Mandatory. LDAP base DN. Example:

ldap_base_dn ou=mail,dc=example,dc=com

ldap_mail_attribute <attribute name>

Mandatory. LDAP mail attribute. Example:

ldap_mail_attribute mail

ldap_ssl <0/1>

Mandatory. Use TLS (SSL) for connection to LDAP server. Example:

ldap_ssl 0

ldap_ssl_version <sslv2 /sslv3 / tlsv1 / tlsv1_1 / tlsv1_2>

Mandatory if "ldap_ssl" is 1. Protocol version of TLS. Example:

ldap_ssl_version tlsv1

ldap_cachain <file path>

LDAP CA chain file Example:

ldap_cachain /etc/ldap/cert/cachain.pem

queue_transport <name>

Mandatory. Postfix transport parameter for queue Example:

queue_transport sympa

bouncequeue_transport <name>

Mandatory. Postfix transport parameter for bouncequeue Example:

bouncequeue_transport sympabounce

## FILES
$SYSCONFDIR/ldap_alias_manager.conf

Configuration file.

## SEE ALSO
ldap_alias_manager(8).


title: list_config(5)

summary: Configuration file for mailing list

text:
# list_config(5)

## NAME
list_config - Configuration file for mailing list

## DESCRIPTION
See sympa_config(5).


title: nrcpt_by_domain.conf(5)

text:
# nrcpt_by_domain.conf(5)

## NAME
nrcpt_by_domain.conf - Grouping factor for SMTP sessions by recipient domains

## DESCRIPTION
nrcpt_by_domain.conf defines limit of the number of recipients for a particular domain in each session.

TBD.

## FILES
$DEFAULTDIR/nrcpt_by_domain.conf

Distribution default. This files should not be edited.

$SYSCONFDIR/nrcpt_by_domain.conf

Configuration file.

## SEE ALSO
bulk(8), sympa_config(5).

## HISTORY
This document was initially written by IKEDA Soji <ikeda@conversion.co.jp>.


sympa.conf

title: sympa.conf(5)

text:
# sympa.conf(5)

## NAME
sympa.conf, robot.conf - Configuration file for default site and robot

## DESCRIPTION
See sympa_config(5).


sympa.wsdl

title: sympa.wsdl(5)

text:
# sympa.wsdl(5)

## NAME
sympa.wsdl - Service description of SOAP HTTP interface for Sympa

## DESCRIPTION
sympa.wsdl defines services provided by SOAP HTTP interface for Sympa.

TBD.

## FILES
$DEFAULTDIR/sympa.wsdl

Distribution default. This file should not be edited.

$SYSCONFDIR/sympa.wsdl

$SYSCONFDIR/<robot name>/sympa.wsdl

Configuration files for site-wide default and each robot.

## SEE ALSO
sympa_soap_server(8).

## HISTORY
This document was initially written by IKEDA Soji <ikeda@conversion.co.jp>.