pipewire-pulse-module-device-manager

title: pipewire-pulse-module-device-manager(7)

summary: Device manager extension

text:
# pipewire-pulse-module-device-manager(7)

## NAME
pipewire-pulse-module-device-manager - Device manager extension

## MODULE NAME
module-device-manager

## MODULE OPTIONS

- do_routing: Automatically route streams based on a priority list (unique per-role)?

- on_hotplug: When new device becomes available, recheck streams?

- on_rescue: When device becomes unavailable, recheck streams?


pipewire-pulse-module-device-restore

package: pipewire-libs-devel

title: pipewire-pulse-module-device-restore(7)

summary: Device restore extension

text:
# pipewire-pulse-module-device-restore(7)

## NAME
pipewire-pulse-module-device-restore - Device restore extension

## MODULE NAME
module-device-restore

## MODULE OPTIONS

- restore_port: Save/restore port?

- restore_volume: Save/restore volumes?

- restore_muted: Save/restore muted states?

- restore_formats: Save/restore saved formats?

branch: sisyphus


pipewire-pulse-module-echo-cancel

title: pipewire-pulse-module-echo-cancel(7)

summary: Echo Cancel

text:
# pipewire-pulse-module-echo-cancel(7)

## NAME
pipewire-pulse-module-echo-cancel - Echo Cancel

## MODULE NAME
module-echo-cancel

## MODULE OPTIONS

- source_name: name for the source

- source_properties: properties for the source

- source_master: name of source to filter

- sink_name: name for the sink

- sink_properties: properties for the sink

- sink_master: name of sink to filter

- rate: sample rate

- channels: number of channels

- channel_map: channel map

- aec_method: implementation to use

- aec_args: parameters for the AEC engine

## SEE ALSO
libpipewire-module-echo-cancel


pipewire-pulse-module-gsettings

title: pipewire-pulse-module-gsettings(7)

summary: GSettings

text:
# pipewire-pulse-module-gsettings(7)

## NAME
pipewire-pulse-module-gsettings - GSettings

## MODULE NAME
module-gsettings

## MODULE OPTIONS
No options.


pipewire-pulse-module-jackdbus-detect

summary: JackDBus Detect

text:
# pipewire-pulse-module-jackdbus-detect(7)

## NAME
pipewire-pulse-module-jackdbus-detect - JackDBus Detect

## MODULE NAME
module-jackdbus-detect

## MODULE OPTIONS

- channels: number of channels

- sink_name: name for the sink

- sink_properties: properties for the sink

- sink_client_name: jack client name

- sink_channels: number of channels

- sink_channel_map: channel map

- source_name: name for the source

- source_properties: properties for the source

- source_client_name: jack client name

- source_channels: number of channels

- source_channel_map: channel map

- connect: connect ports?

## SEE ALSO
libpipewire-module-jackdbus-detect


pipewire-pulse-module-ladspa-sink

title: pipewire-pulse-module-ladspa-sink(7)

summary: LADSPA Sink

text:
# pipewire-pulse-module-ladspa-sink(7)

## NAME
pipewire-pulse-module-ladspa-sink - LADSPA Sink

## MODULE NAME
module-ladspa-sink

## MODULE OPTIONS

- sink_name: name for the sink

- sink_properties: properties for the sink

- sink_input_properties: properties for the sink input

- master: name of sink to filter

- sink_master: name of sink to filter

- format: sample format

- rate: sample rate

- channels: number of channels

- channel_map: input channel map

- plugin: ladspa plugin name

- label: ladspa plugin label

- control: comma separated list of input control values

- input_ladspaport_map: comma separated list of input LADSPA port names

- output_ladspaport_map: comma separated list of output LADSPA port names

## SEE ALSO
libpipewire-module-filter-chain


pipewire-pulse-module-ladspa-source

title: pipewire-pulse-module-ladspa-source(7)

summary: LADSPA Source

text:
# pipewire-pulse-module-ladspa-source(7)

## NAME
pipewire-pulse-module-ladspa-source - LADSPA Source

## MODULE NAME
module-ladspa-source

## MODULE OPTIONS

- source_name: name for the source

- source_properties: properties for the source

- source_output_properties: properties for the source output

- master: name of source to filter

- source_master: name of source to filter

- format: sample format

- rate: sample rate

- channels: number of channels

- channel_map: input channel map

- plugin: ladspa plugin name

- label: ladspa plugin label

- control: comma separated list of input control values

- input_ladspaport_map: comma separated list of input LADSPA port names

- output_ladspaport_map: comma separated list of output LADSPA port names

## SEE ALSO
libpipewire-module-filter-chain


pipewire-pulse-module-loopback

title: pipewire-pulse-module-loopback(7)

summary: Loopback

text:
# pipewire-pulse-module-loopback(7)

## NAME
pipewire-pulse-module-loopback - Loopback

## MODULE NAME
module-loopback

## MODULE OPTIONS

- source: source to connect to

- sink: sink to connect to

- latency_msec: latency in ms

- rate: sample rate

- channels: number of channels

- channel_map: channel map

- sink_input_properties: proplist

- source_output_properties: proplist

- source_dont_move: boolean

- sink_dont_move: boolean

- remix: remix channels?

## SEE ALSO
libpipewire-module-loopback


summary: Pulseaudio TCP Protocol

text:
# pipewire-pulse-module-native-protocol-tcp(7)

## NAME
pipewire-pulse-module-native-protocol-tcp - Pulseaudio TCP Protocol

## MODULE NAME
module-native-protocol-tcp

## MODULE OPTIONS

- port: TCP port number

- listen: address to listen on


pipewire-pulse-module-null-sink

title: pipewire-pulse-module-null-sink(7)

summary: Null Sink

text:
# pipewire-pulse-module-null-sink(7)

## NAME
pipewire-pulse-module-null-sink - Null Sink

## MODULE NAME
module-null-sink

## MODULE OPTIONS

- sink_name: name of sink

- sink_properties: properties for the sink

- format: sample format

- rate: sample rate

- channels: number of channels

- channel_map: channel map


pipewire-pulse-module-pipe-sink

title: pipewire-pulse-module-pipe-sink(7)

summary: Pipe Sink

text:
# pipewire-pulse-module-pipe-sink(7)

## NAME
pipewire-pulse-module-pipe-sink - Pipe Sink

## MODULE NAME
module-pipe-sink

## MODULE OPTIONS

- file: name of the FIFO special file to use

- sink_name: name for the sink

- sink_properties: sink properties

- format: sample format

- rate: sample rate

- channels: number of channels

- channel_map: channel map

- use_system_clock_for_timing: yes or no

## SEE ALSO
libpipewire-module-pipe-tunnel


pipewire-pulse-module-pipe-source

title: pipewire-pulse-module-pipe-source(7)

summary: Pipe Source

text:
# pipewire-pulse-module-pipe-source(7)

## NAME
pipewire-pulse-module-pipe-source - Pipe Source

## MODULE NAME
module-pipe-source

## MODULE OPTIONS

- file: name of the FIFO special file to use

- source_name: name for the source

- source_properties: source properties

- format: sample format

- rate: sample rate

- channels: number of channels

- channel_map: channel map

## SEE ALSO
libpipewire-module-pipe-tunnel


pipewire-pulse-module-raop-discover

title: pipewire-pulse-module-raop-discover(7)

summary: RAOP Discover

text:
# pipewire-pulse-module-raop-discover(7)

## NAME
pipewire-pulse-module-raop-discover - RAOP Discover

## MODULE NAME
module-raop-discover

## MODULE OPTIONS
No options.

## SEE ALSO
libpipewire-module-raop-discover


pipewire-pulse-module-remap-sink

title: pipewire-pulse-module-remap-sink(7)

summary: Remap Sink

text:
# pipewire-pulse-module-remap-sink(7)

## NAME
pipewire-pulse-module-remap-sink - Remap Sink

## MODULE NAME
module-remap-sink

## MODULE OPTIONS

- sink_name: name for the sink

- sink_properties: properties for the sink

- master: name of sink to remap

- master_channel_map: channel map

- format: sample format

- rate: sample rate

- channels: number of channels

- channel_map: channel map

- resample_method: resampler

- remix: remix channels?

## SEE ALSO
libpipewire-module-loopback


pipewire-pulse-module-remap-source

title: pipewire-pulse-module-remap-source(7)

summary: Remap Source

text:
# pipewire-pulse-module-remap-source(7)

## NAME
pipewire-pulse-module-remap-source - Remap Source

## MODULE NAME
module-remap-source

## MODULE OPTIONS

- source_name: name for the source

- source_properties: properties for the source

- master: name of source to filter

- master_channel_map: channel map

- format: sample format

- rate: sample rate

- channels: number of channels

- channel_map: channel map

- resample_method: resampler

- remix: remix channels?

## SEE ALSO
libpipewire-module-loopback


pipewire-pulse-module-roc-sink

title: pipewire-pulse-module-roc-sink(7)

summary: ROC Sink

text:
# pipewire-pulse-module-roc-sink(7)

## NAME
pipewire-pulse-module-roc-sink - ROC Sink

## MODULE NAME
module-roc-sink

## MODULE OPTIONS

- sink_name: name for the sink

- sink_properties: properties for the sink

- fec_code: empty>|disable|rs8m|ldpc

- remote_ip: remote receiver ip

- remote_source_port: remote receiver port for source packets

- remote_repair_port: remote receiver port for repair packets

- remote_control_port: remote receiver port for control packets

## SEE ALSO
libpipewire-module-roc-sink


pipewire-pulse-module-roc-sink-input

title: pipewire-pulse-module-roc-sink-input(7)

summary: ROC Sink Input

text:
# pipewire-pulse-module-roc-sink-input(7)

## NAME
pipewire-pulse-module-roc-sink-input - ROC Sink Input

## MODULE NAME
module-roc-sink-input

## MODULE OPTIONS

- sink: name for the sink

- sink_input_properties: properties for the sink_input

- resampler_profile: empty>|high|medium|low

- fec_code: empty>|disable|rs8m|ldpc

- sess_latency_msec: target network latency in milliseconds

- local_ip: local receiver ip

- local_source_port: local receiver port for source packets

- local_repair_port: local receiver port for repair packets

- local_control_port: local receiver port for control packets

## SEE ALSO
libpipewire-module-roc-source


pipewire-pulse-module-roc-source

title: pipewire-pulse-module-roc-source(7)

summary: ROC Source

text:
# pipewire-pulse-module-roc-source(7)

## NAME
pipewire-pulse-module-roc-source - ROC Source

## MODULE NAME
module-roc-source

## MODULE OPTIONS

- source_name: name for the source

- source_properties: properties for the source

- resampler_profile: empty>|high|medium|low

- fec_code: empty>|disable|rs8m|ldpc

- sess_latency_msec: target network latency in milliseconds

- local_ip: local receiver ip

- local_source_port: local receiver port for source packets

- local_repair_port: local receiver port for repair packets

- local_control_port: local receiver port for control packets

## SEE ALSO
libpipewire-module-roc-source


pipewire-pulse-module-rtp-recv

title: pipewire-pulse-module-rtp-recv(7)

summary: RTP Receiver

text:
# pipewire-pulse-module-rtp-recv(7)

## NAME
pipewire-pulse-module-rtp-recv - RTP Receiver

## MODULE NAME
module-rtp-recv

## MODULE OPTIONS

- sink: name of the sink

- sap_address: multicast address to listen on

- latency_msec: latency in ms

- stream_properties: properties for the stream

## SEE ALSO
libpipewire-module-rtp-sap


pipewire-pulse-module-rtp-send

title: pipewire-pulse-module-rtp-send(7)

summary: RTP Sender

text:
# pipewire-pulse-module-rtp-send(7)

## NAME
pipewire-pulse-module-rtp-send - RTP Sender

## MODULE NAME
module-rtp-send

## MODULE OPTIONS

- source: name of the source

- format: sample format

- channels: number of channels

- rate: sample rate

- destination_ip: destination IP address

- source_ip: source IP address

- port: port number

- mtu: maximum transfer unit

- loop: loopback to local host?

- ttl: ttl value

- inhibit_auto_suspend: always|never|only_with_non_monitor_sources

- stream_name: name of the stream

- stream_properties: properties for the stream

- enable_opus: enable OPUS codec

## SEE ALSO
libpipewire-module-rtp-sink


summary: Simple TCP Protocol

text:
# pipewire-pulse-module-simple-protocol-tcp(7)

## NAME
pipewire-pulse-module-simple-protocol-tcp - Simple TCP Protocol

## MODULE NAME
module-simple-protocol-tcp

## MODULE OPTIONS

- rate: sample rate

- format: sample format

- channels: number of channels

- channel_map: number of channels

- sink: sink to connect to

- source: source to connect to

- playback: enable playback?

- record: enable record?

- port: TCP port number

- listen: address to listen on

## SEE ALSO
libpipewire-module-protocol-simple


pipewire-pulse-module-stream-restore

title: pipewire-pulse-module-stream-restore(7)

summary: Stream restore extension

text:
# pipewire-pulse-module-stream-restore(7)

## NAME
pipewire-pulse-module-stream-restore - Stream restore extension

## MODULE NAME
module-stream-restore

## MODULE OPTIONS

- restore_device: Save/restore sinks/sources?

- restore_volume: Save/restore volumes?

- restore_muted: Save/restore muted states?

- on_hotplug: This argument is obsolete, please remove it from configuration

- on_rescue: This argument is obsolete, please remove it from configuration

- fallback_table: filename


pipewire-pulse-module-switch-on-connect

summary: Switch on Connect

text:
# pipewire-pulse-module-switch-on-connect(7)

## NAME
pipewire-pulse-module-switch-on-connect - Switch on Connect

## MODULE NAME
module-switch-on-connect

## MODULE OPTIONS

- only_from_unavailable: boolean, only switch from unavailable ports (not implemented yet)

- ignore_virtual: boolean, ignore new virtual sinks and sources, defaults to true

- blocklist: regex, ignore matching devices, default=hdmi


pipewire-pulse-module-tunnel-sink

title: pipewire-pulse-module-tunnel-sink(7)

summary: Tunnel Sink

text:
# pipewire-pulse-module-tunnel-sink(7)

## NAME
pipewire-pulse-module-tunnel-sink - Tunnel Sink

## MODULE NAME
module-tunnel-sink

## MODULE OPTIONS

- server: address

- sink: name of the remote sink

- sink_name: name for the local sink

- sink_properties: properties for the local sink

- reconnect_interval_ms: interval to try reconnects, 0 or omitted if disabled

- format: sample format

- channels: number of channels

- rate: sample rate

- channel_map: channel map

- latency_msec: fixed latency in ms

- cookie: cookie file path

## SEE ALSO
libpipewire-module-pulse-tunnel


pipewire-pulse-module-tunnel-source

title: pipewire-pulse-module-tunnel-source(7)

summary: Tunnel Source

text:
# pipewire-pulse-module-tunnel-source(7)

## NAME
pipewire-pulse-module-tunnel-source - Tunnel Source

## MODULE NAME
module-tunnel-source

## MODULE OPTIONS

- server: address

- source: name of the remote source

- source_name: name for the local source

- source_properties: properties for the local source

- reconnect_interval_ms: interval to try reconnects, 0 or omitted if disabled

- format: sample format

- channels: number of channels

- rate: sample rate

- channel_map: channel map

- latency_msec: fixed latency in ms

- cookie: cookie file path

## SEE ALSO
libpipewire-module-pulse-tunnel


pipewire-pulse-module-virtual-sink

title: pipewire-pulse-module-virtual-sink(7)

summary: Virtual Sink

text:
# pipewire-pulse-module-virtual-sink(7)

## NAME
pipewire-pulse-module-virtual-sink - Virtual Sink

## MODULE NAME
module-virtual-sink

## MODULE OPTIONS

- sink_name: name for the sink

- sink_properties: properties for the sink

- master: name of sink to filter

- channels: number of channels

- channel_map: channel map

- use_volume_sharing: yes or no

- force_flat_volume: yes or no

## SEE ALSO
libpipewire-module-loopback


pipewire-pulse-module-virtual-source

title: pipewire-pulse-module-virtual-source(7)

summary: Virtual Source

text:
# pipewire-pulse-module-virtual-source(7)

## NAME
pipewire-pulse-module-virtual-source - Virtual Source

## MODULE NAME
module-virtual-source

## MODULE OPTIONS

- source_name: name for the source

- source_properties: properties for the source

- master: name of source to filter

- uplink_sink: name> (optional)

- channels: number of channels

- channel_map: channel map

- use_volume_sharing: yes or no

- force_flat_volume: yes or no

## SEE ALSO
libpipewire-module-loopback


title: pipewire-pulse-module-x11-bell(7)

summary: X11 Bell

text:
# pipewire-pulse-module-x11-bell(7)

## NAME
pipewire-pulse-module-x11-bell - X11 Bell

## MODULE NAME
module-x11-bell

## MODULE OPTIONS

- sink: sink to connect to

- sample: the sample to play

- display: X11 display

- xauthority: X11 Authority

## SEE ALSO
libpipewire-module-x11-bell


pipewire-pulse-module-zeroconf-discover

summary: Zeroconf Discover

text:
# pipewire-pulse-module-zeroconf-discover(7)

## NAME
pipewire-pulse-module-zeroconf-discover - Zeroconf Discover

## MODULE NAME
module-zeroconf-discover

## MODULE OPTIONS
•

latency_msec: fixed latency in ms

## SEE ALSO
libpipewire-module-zeroconf-discover


pipewire-pulse-module-zeroconf-publish

summary: Zeroconf Publish

text:
# pipewire-pulse-module-zeroconf-publish(7)

## NAME
pipewire-pulse-module-zeroconf-publish - Zeroconf Publish

## MODULE NAME
module-zeroconf-publish

## MODULE OPTIONS
No options.


pipewire-pulse-modules

title: pipewire-pulse-modules(7)

summary: PipeWire Pulseaudio modules

text:
# pipewire-pulse-modules(7)

## NAME
pipewire-pulse-modules - PipeWire Pulseaudio modules

## DESCRIPTION
PipeWire's Pulseaudio emulation implements several Pulseaudio modules. It only supports its own built-in modules, and cannot load external modules written for Pulseaudio.

## LOADING MODULES
The built-in modules can be loaded using Pulseaudio client programs, for example pactl load-module <module-name> <module-options>. They can also added to pipewire-pulse.conf, typically by a drop-in file in ~/.config/pipewire/pipewire-pulse.conf.d/ containing the module name and its arguments

```
# ~/.config/pipewire/pipewire-pulse.conf.d/custom.conf
pulse.cmd = [

    { cmd = "load-module" args = "module-null-sink sink_name=foo" flags = [ ] }
]
```

To list all modules currently loaded, with their arguments:

```
pactl list modules
```

For a short list of loaded modules:

```
pactl list modules short
```

Modules may be unloaded using either the module-name or index number:

```
pactl load-module <module-name> <parameters>
pactl unload-module <module-name|index#>
```

## COMMON MODULE OPTIONS
Most modules that create streams/devices support the following properties:

### sink_name, source_name
Name for the sink (resp. source). Allowed characters in the name are a-z, A-Z, numbers, period (.) and underscore (_). The length must be 1-128 characters.

### format
The sample format. The supported audio formats are:

### PCM

- u8: unsigned 8-bit integer

- aLaw: A-law encoded 8-bit integer

- uLaw: μ-law encoded 8-bit integer

- s16le: signed 16-bit little-endian integer

- s16be: signed 16-bit big-endian integer

- s16, s16ne: native-endian aliases for s16le or s16be

- s16re: reverse-endian alias for s16le or s16be

- float32le: 32-bit little-endian float

- float32be: 32-bit big-endian float

- float32, float32ne: native-endian aliases for float32le or float32be

- float32re: reverse-endian alias for float32le or float32be

- s32le: signed 32-bit little-endian integer

- s32be: signed 32-bit big-endian integer

- s32, s32ne: native-endian aliases for s32le or s32be

- s32re: reverse-endian alias for s32le or s32be

- s24le: signed 24-bit little-endian integer (note: ALSA calls this "S24_3LE")

- s24be: signed 24-bit big-endian integer (note: ALSA calls this "S24_3BE")

- s24, s24ne: native-endian aliases for s24le or s24be

- s24re: reverse-endian alias for s24le or s24be

- s24-32le: signed 24-bit little-endian integer, packed into a 32-bit integer so that the 8 most significant bits are ignored (note: ALSA calls this "S24_LE")

- s24-32be: signed 24-bit big-endian integer, packed into a 32-bit integer so that the 8 most significant bits are ignored (note: ALSA calls this "S24_BE")

- s24-32, s24-32ne: native-endian aliases for s24-32le or s24-32be

- s24-32re: reverse-endian alias for s24-32le or s24-32be

### Compressed audio formats
Below is a list of all supported compressed formats. The code at the beginning of each line is used whenever a textual identifier for a format is needed (for example in configuration files or on the command line). The formats whose identifier ends with -iec61937 have to be wrapped in IEC 61937 frames, which makes the compressed audio behave more like normal PCM audio.

- ac3-iec61937: Dolby Digital (DD / AC-3 / A/52)

- eac3-iec61937: Dolby Digital Plus (DD+ / E-AC-3)

- mpeg-iec61937: MPEG-1 or MPEG-2 Part 3 (not MPEG-2 AAC)

- dts-iec61937: DTS

- mpeg2-aac-iec61937: MPEG-2 AAC (supported since PulseAudio 4.0)

- truehd-iec61937: Dolby TrueHD (added in PulseAudio 13.0, but doesn't work yet in practice)

- dtshd-iec61937: DTS-HD Master Audio (added in PulseAudio 13.0, but doesn't work yet in practice)

- pcm: PCM (not a compressed format, but listed here, because pcm is one of the recognized encoding identifiers)

- any: (special identifier for indicating that any encoding can be used)

### rate
The sample rate.

### channels
Number of audio channels.

### channel_map
A channel map. A list of comma-separated channel names. The currently defined channel names are: left, right, mono, center, front-left, front-right, front-center, rear-center, rear-left, rear-right, lfe, subwoofer, front-left-of-center, front-right-of-center, side-left, side-right, aux0, aux1 to aux15, top-center, top-front-left, top-front-right, top-front-center, top-rear-left, top-rear-right, top-rear-center

### sink_properties, source_properties
Set additional properties of the sink/source. For example, you can set the description directly when the module is loaded by setting this parameter.

```
load-module module-alsa-sink sink_name=headphones sink_properties=device.description=Headphones
```

## BUILT-IN MODULES

- pipewire-pulse-module-alsa-sink(7)

- pipewire-pulse-module-alsa-source(7)

- pipewire-pulse-module-always-sink(7)

- pipewire-pulse-module-combine-sink(7)

- pipewire-pulse-module-device-manager(7)

- pipewire-pulse-module-device-restore(7)

- pipewire-pulse-module-echo-cancel(7)

- pipewire-pulse-module-jackdbus-detect(7)

- pipewire-pulse-module-ladspa-sink(7)

- pipewire-pulse-module-ladspa-source(7)

- pipewire-pulse-module-loopback(7)

- pipewire-pulse-module-native-protocol-tcp(7)

- pipewire-pulse-module-null-sink(7)

- pipewire-pulse-module-pipe-source(7)

- pipewire-pulse-module-pipe-sink(7)

- pipewire-pulse-module-raop-discover(7)

- pipewire-pulse-module-remap-sink(7)

- pipewire-pulse-module-remap-source(7)

- pipewire-pulse-module-roc-sink(7)

- pipewire-pulse-module-roc-sink-input(7)

- pipewire-pulse-module-roc-source(7)

- pipewire-pulse-module-rtp-recv(7)

- pipewire-pulse-module-rtp-send(7)

- pipewire-pulse-module-simple-protocol-tcp(7)

- pipewire-pulse-module-stream-restore(7)

- pipewire-pulse-module-switch-on-connect(7)

- pipewire-pulse-module-tunnel-sink(7)

- pipewire-pulse-module-tunnel-source(7)

- pipewire-pulse-module-virtual-sink(7)

- pipewire-pulse-module-virtual-source(7)

- pipewire-pulse-module-x11-bell(7)

- pipewire-pulse-module-zeroconf-discover(7)

- pipewire-pulse-module-zeroconf-publish(7)

- pipewire-pulse-module-gsettings(7)

## AUTHORS
The PipeWire Developers <https://gitlab.freedesktop.org/pipewire/pipewire/issues>; PipeWire is available from <https://pipewire.org>

## SEE ALSO
pipewire-pulse(1)


title: provider-pkcs11(7)

text:
# provider-pkcs11(7)

## NAME
pkcs11-provider - An OpenSSL provider that allows one to directly interface with pkcs11 drivers.

## DESCRIPTION
Starting with version 3.0 the OpenSSL project introduced a new modular system to extend OpenSSL that replaces the deprecated Engines modules.

Providers(1) are loaded via configuration directives in the openssl configuration file (or directly loaded by applications).

The pkcs11 provider allows applications linked to openssl to use keys and cryptographic operations from a hardware or software token via their PKCS#11(2) driver and the use of pkcs11 URIs(3).

The pkcs11 provider can be configured to be automatically loaded via openssl.cnf

## CONFIGURATION
Configuration options recognized by the provider

### pkcs11-module-path
A file path to the pkcs11 driver to be used

Default: If compiled with p11-kit defaults to its proxy driver, otherwise none.

NOTE: See also PKCS11_PROVIDER_MODULE in the environment variables section.

Example:

pkcs11-module-path = /usr/lib64/opensc-pkcs11.so

### pkcs11-module-init-args
Non-standard initialization arguments some pkcs11 driver may need. Generally not used, but some software tokens like NSS’s softokn require this.

Default: None

Example:

pkcs11-module-init-args = configDir=/etc/pki/token

### pkcs11-module-token-pin
The user PIN to be used with the token. If a PIN is not set in configuration it can be asked interactively (if the application uses prompters), or it can be specified together with the key identifiers in the pkcs11 URI directly. When a file is specified the file must be a text file containing just the PIN on the first line and a terminator.

Default: None

Example:

pkcs11-module-token-pin = file:/etc/pki/pin.txt

```
cat /etc/pki/pin.txt
123456

```

### pkcs11-module-allow-export
Whether the pkcs11 provider will allow one to export public keys through OpenSSL. OpenSSL often tries to export public keys from non-default providers to the default provider, and then use OpenSSL own functions to handle whatever operation is associated with the public key. This option can be useful to force public key operations to be executed on the token, for example in case the pkcs11 is an accelerator that has better performance on signature checking or asymmetric encryption than OpenSSL’s code.

Default: 0 (Allow Export)

Example:

pkcs11-module-allow-export = 1 (This disallows export of public keys)

### pkcs11-module-cache-keys
Whether the pkcs11-provider should ask the token to cache token keys in the session. This is used in some tokens as a performance optimizations. For example software tokens that store keys encrypted can keep a copy of the key in the session to speed up access. Or Networked HSMs that allow exporting key material can cache the key in the session instead of re-requesting it over the network.

Two options are available:

•

true

•

false

Default: true (Note: if the token does not support session caching, then caching will be auto-disabled after the first attempt)

Example:

pkcs11-module-cache-keys = false (Disable any attempt of caching keys in the session)

### pkcs11-module-cache-pins
Whether the pkcs11-provider should cache a pin entered interactively. This is useful to allow starting a service and providing the pin only manually, yet let the service perform multiple logins as needed, for example after forking.

Only one option is currently available:

•

cache: Caches the PIN

Default: unset (No caching)

Example:

pkcs11-module-cache-pins = cache (Will cache a pin that has been entered manually)

### pkcs11-module-cache-sessions
Allows one to tune how many pkcs11 sessions may be kept open and cached for rapid use. This parameter is adjusted based on the maximum number of sessions the token declares as supported. Note that the login session is always cached to keep the token operable.

Default: 5

Example:

pkcs11-module-cache-sessions = 0 (Disables caching)

### pkcs11-module-login-behavior
Whether the pkcs11 provider will attempt to login to the token when a public key is being requested.

Three options are available:

•

auto: Try without but fallback to login behavior if no keys are found

•

always: Always login before trying to load public keys (this is required by some HSMs)

•

never: Never login for public keys

Default: “auto”

Example:

pkcs11-module-login-behavior = always (Always tries to login before loading public keys)

### pkcs11-module-load-behavior
Whether the pkcs11-provider immediately loads an initializes the pkcs11 module as soon as OpenSSL loads the provider (generally at application startup), or defer initialization until the first time a pkcs11 key is loaded (or some other operation explicitly requiring the pkcs11 provider is requested).

Only one option is available:

•

early: Loads the pkcs11 module immediately

Default: unset (Loads only at first use)

Example:

pkcs11-module-load-behavior = early (Loads pkcs11 module immediately at application startup)

### pkcs11-module-quirks
Workarounds that may be needed to deal with some tokens and cannot be autodetcted yet are not appropriate defaults.

### no-deinit
It prevents de-initing when OpenSSL winds down the provider. NOTE this option may leak memory and may cause some modules to misbehave if the application intentionally unloads and reloads them.

### no-operation-state
OpenSSL by default assumes contexts with operations in flight can be easily duplicated. That is only possible if the tokens support getting and setting the operation state. If the quirk is enabled the context duplication is not performed.

### no-session-callbacks
Some implementatations of PKCS11 don’t allow setting pApplication and Notify callback functions in C_OpenSession. This option sets NULL values for both callbacks.

### no-allowed-mechanisms
Some implementatations of PKCS11 don’t support CKA_ALLOWED_MECHANISMS attribute on keys. Setting this quirk prevents the provider from attempting to set and read this attribute.

Default: none

Example:

pkcs11-module-quirks = no-deinit no-operation-state (Disables deinitialization, blocks context duplication)

### pkcs11-module-block-operations
Allows one to block specific “provider operations” even if the token actually supports the necessary mechanisms. This is useful to work around cases where one wants to enforce use of the token for all operations by setting ?provider=pkcs11 in the default properties but wants an exception for a specific type of operation like digests. NOTE: some operations may depend on others or may be fundamental to the correct working of the provider, so not all configurations of this parameter will work. Use carefully.

Default: none

Example: pkcs11-module-block-operations = digest (Disables digest mechanisms, which will be instead routed to the OpenSSL default provider in most configurtions)

### pkcs11-module-assume-fips
Assume the token used by the PKCS#11 module is FIPS certified.

Due to the incomplete specification for signalization of the certification from the pkcs11 modules, this can not be determined automatically. If you know your token is FIPS certified, you need to set this configuration option to true. Otherwise the pkcs11-provider will not work in FIPS Mode.

Default: False

Example:

pkcs11-module-assume-fips = true

## ENVIRONMENT VARIABLES
Environment variables recognized by the provider

### PKCS11_PROVIDER_MODULE
This variable can be used to set a different pkcs11 driver to be used. It is useful when an application needs to use a different driver than the rest of the system. This environment variable overrides the pkcs11-module-path option sets in openssl.cnf

Example:

PKCS11_PROVIDER_MODULE = /usr/lib64/opensc-pkcs11.so

### PKCS11_PROVIDER_DEBUG
This variable can be set to obtain debug information. Two sub-options can be specified: file, level

The normal debug_level is 1, if a higher level is provider then additional information (like all supported mechanism info for each slot) is printed in the specified debug file. The comma character separates options, and the colon character is used to separate an option and its value. There is no escape character, therefore the characters `,' and `:' cannot be used in values.

Examples:

PKCS11_PROVIDER_DEBUG=file:/tmp/debug.log

PKCS11_PROVIDER_DEBUG=file:/dev/stderr,level:2

## USE IN OLDER APPLICATIONS (URIs in PEM files)
It is strongly suggested to update applications to use the new OSSL_STORE API provided by OpenSSL 3.0 which accepts URIs to transparenly load keys from either files or any other supported mechanism including PKCS#11 URIs.

However, for those applications that cannot yet be changed, there is tool to generate a “wrapper” PEM file that contains the PKCS#11 URI needed to identify a key on the a token.

This PEM file can be loaded via the clasic methods used to parse PEM/DER representations of keys and will trigger the use of the pkcs11-provider decoders when the provider is loaded. An error will be returned if the provider is not pre-loaded or an older version of OpenSSL is used.

In tools/uri2pem.py there is a sample python script that can take a key URI and produce a PEM file that references it. Note that storing PINs within these PEM files is not secure. These files are not encrypted.

The following command can be used to list all keys on a token and print their identifying URI:

```
openssl storeutl -keys -text pkcs11:

```

## EXAMPLES
openssl.cnf:

```
HOME = .
# Use this in order to automatically load providers.
openssl_conf = openssl_init
[openssl_init]
providers = provider_sect
[provider_sect]
default = default_sect
pkcs11 = pkcs11_sect
[default_sect]
activate = 1
[pkcs11_sect]
module = /usr/lib64/ossl-modules/pkcs11.so
pkcs11-module-path = /usr/lib64/pkcs11/vendor_pkcs11.so
pkcs11-module-token-pin = /etc/ssl/pinfile.txt
activate = 1

```

## SEE ALSO
1.

PROVIDER(7) man page - https://www.openssl.org/docs/manmaster/man7/provider.html

2.

PKCS#11 Technical committe and standards - https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=pkcs11

3.

PKCS#11 URI Scheme - RFC 7512 - https://www.rfc-editor.org/rfc/rfc7512


title: po4a(7)

text:
# po4a(7)

## NAME
po4a - framework to translate documentation and other materials

## Introduction
po4a (PO for anything) eases the maintenance of documentation translation using the classical gettext tools. The main feature of po4a is that it decouples the translation of content from its document structure.

This document serves as an introduction to the po4a project with a focus on potential users considering whether to use this tool and on the curious wanting to understand why things are the way they are.

## Why po4a?
The philosophy of Free Software is to make the technology truly available to everyone. But licensing is not the only consideration: untranslated free software is useless for non-English speakers. Therefore, we still have some work to do to make software available to everybody.

This situation is well understood by most projects and everybody is now convinced of the necessity to translate everything. Yet, the actual translations represent a huge effort of many individuals, crippled by small technical difficulties.

Thankfully, Open Source software is actually very well translated using the gettext tool suite. These tools are used to extract the strings to translate from a program and present the strings to translate in a standardized format (called PO files, or translation catalogs). A whole ecosystem of tools has emerged to help the translators actually translate these PO files. The result is then used by gettext at run time to display translated messages to the end users.

Regarding documentation, however, the situation still somewhat disappointing. At first translating documentation may seem to be easier than translating a program as it would seem that you just have to copy the documentation source file and start translating the content. However, when the original documentation is modified, keeping track of the modifications quickly turns into a nightmare for the translators. If done manually, this task is unpleasant and error-prone.

Outdated translations are often worse than no translation at all. End-users can be tricked by documentation describing an old behavior of the program. Furthermore, they cannot interact directly with the maintainers since they don't speak English. Additionally, the maintainer cannot fix the problem as they don't know every language in which their documentation is translated. These difficulties, often caused by poor tooling, can undermine the motivation of volunteer translators, further aggravating the problem.

The goal of the po4a project is to ease the work of documentation translators. In particular, it makes documentation translations maintainable.

The idea is to reuse and adapt the gettext approach to this field. As with gettext, texts are extracted from their original locations and presented to translators as PO translation catalogs. The translators can leverage the classical gettext tools to monitor the work to do, collaborate and organize as teams. po4a then injects the translations directly into the documentation structure to produce translated source files that can be processed and distributed just like the English files. Any paragraph that is not translated is left in English in the resulting document, ensuring that the end users never see an outdated translation in the documentation.

This automates most of the grunt work of the translation maintenance. Discovering the paragraphs needing an update becomes very easy, and the process is completely automated when elements are reordered without further modification. Specific verification can also be used to reduce the chance of formatting errors that would result in a broken document.

Please also see the FAQ below in this document for a more complete list of the advantages and disadvantages of this approach.

### Supported formats
Currently, this approach has been successfully implemented to several kinds of text formatting formats:

man (mature parser)

The good old manual pages' format, used by so many programs out there. po4a support is very welcome here since this format is somewhat difficult to use and not really friendly to newbies. The Locale::Po4a::Man(3pm) module also supports the mdoc format, used by the BSD man pages (they are also quite common on Linux).

AsciiDoc (mature parser)

This format is a lightweight markup format intended to ease the authoring of documentation. It is for example used to document the git system. Those manpages are translated using po4a. See Locale::Po4a::AsciiDoc for details.

pod (mature parser)

This is the Perl Online Documentation format. The language and extensions themselves are documented using this format in addition to most existing Perl scripts. It makes easy to keep the documentation close to the actual code by embedding them both in the same file. It makes programmer's life easier, but unfortunately, not the translator's, until you use po4a. See Locale::Po4a::Pod for details.

sgml (mature parser)

Even if superseded by XML nowadays, this format is still used for documents which are more than a few screens long. It can even be used for complete books. Documents of this length can be very challenging to update. diff often reveals useless when the original text was re-indented after update. Fortunately, po4a can help you after that process. Currently, only DebianDoc and DocBook DTD are supported, but adding support for a new one is really easy. It is even possible to use po4a on an unknown SGML DTD without changing the code by providing the needed information on the command line. See Locale::Po4a::Sgml(3pm) for details.

TeX / LaTeX (mature parser)

The LaTeX format is a major documentation format used in the Free Software world and for publications. The Locale::Po4a::LaTeX(3pm) module was tested with the Python documentation, a book and some presentations.

text (mature parser)

The Text format is the base format for many formats that include long blocks of text, including Markdown, fortunes, YAML front matter section, debian/changelog, and debian/control. This supports the common format used in Static Site Generators, READMEs, and other documentation systems. See Locale::Po4a::Text(3pm) for details.

xml and XHMTL (probably mature parser)

The XML format is a base format for many documentation formats. Currently, the DocBook DTD (see Locale::Po4a::Docbook(3pm) for details) and XHTML are supported by po4a.

BibTex (probably mature parser)

The BibTex format is used alongside LaTex for formatting lists of references (bibliographies). See Locale::Po4a::BibTex for details.

Docbook (probably mature parser)

A XML-based markup language that uses semantic tags to describe documents. See Locale::Po4a:Docbook for greater details.

Guide XML (probably mature parser)

A XML documentation format. This module was developed specifically to help with supporting and maintaining translations of Gentoo Linux documentation up until at least March 2016 (Based on the Wayback Machine). Gentoo have since moved to the DevBook XML format. See Locale::Po4a:Guide for greater details.

Wml (probably mature parser)

The Web Markup Language, do not mixup WML with the WAP stuff used on cell phones. This module relies on the Xhtml module, which itself relies on the XmL module. See Locale::Po4a::Wml for greater details.

Yaml (probably mature parser)

A strict superset of JSON. YAML is often used as systems or configuration projects. YAML is at the core of Red Hat's Ansible. See Locale::Po4a::Yaml for greater details.

RubyDoc (probably mature parser)

The Ruby Document (RD) format, originally the default documentation format for Ruby and Ruby projects before converted to RDoc in 2002. Though apparently the Japanese version of the Ruby Reference Manual still use RD. See Locale::Po4a::RubyDoc for greater details.

Halibut (probably experimental parser)

A documentation production system, with elements similar to TeX, debiandoc-sgml, TeXinfo, and others, developed by Simon Tatham, the developer of PuTTY. See Locale::Po4a:Halibut for greater details.

Ini (probably experimental parser)

Configuration file format popularized by MS-DOS. See Locale::Po4a::Ini for greater details.

texinfo (very highly experimental parser)

All of the GNU documentation is written in this format (it's even one of the requirements to become an official GNU project). The support for Locale::Po4a::Texinfo(3pm) in po4a is still at the beginning. Please report bugs and feature requests.

gemtext (very highly experimental parser)

The native plain text format of the Gemini protocol. The extension ".gmi" is commonly used. Support for this module in po4a is still in its infancy. If you find anything, please file a bug or feature request.

org (very highly experimental parser)

The document format used by the Org mode. Support for this module in po4a is still in its infancy. If you find anything, please file a bug or feature request.

vimhelp (very highly experimental parser)

The format used for Vim help files (and some third-party plugin documentation). Support for this format in po4a is still in its infancy. If you find anything, please file a bug report or feature request.

simplepod (very highly experimental parser)

Similar to the previously mentioned pod, this one adopts the new Pod::Simple as its parser. Since it is newly created, some bugs are expected. If you notice any strange behavior, please let us know. Eventually, this module will replace pod.

Others supported formats

Po4a can also handle some more rare or specialized formats, such as the documentation of compilation options for the 2.4+ Linux kernels (Locale::Po4a::KernelHelp) or the diagrams produced by the dia tool (Locale::Po4a::Dia). Adding a new format is often very easy and the main task is to come up with a parser for your target format. See Locale::Po4a::TransTractor(3pm) for more information about this.

Unsupported formats

Unfortunately, po4a still lacks support for several documentation formats. Many of them would be easy to support in po4a. This includes formats not just used for documentation, such as, package descriptions (deb and rpm), package installation scripts questions, package changelogs, and all the specialized file formats used by programs such as game scenarios or wine resource files.

## Using po4a
The easiest way to use this tool in your project is to write a configuration file for the po4a program, and only interact with this program. Please refer to its documentation, in po4a(1). The rest of this section provides more details for the advanced users of po4a wanting to deepen their understanding.

### Detailed schema of the po4a workflow
Make sure to read po4a(1) before this overly detailed section to get a simplified overview of the po4a workflow. Come back here when you want to get the full scary picture, with almost all details.

In the following schema, master.doc is an example name for the documentation to be translated; XX.doc is the same document translated in the language XX while doc.XX.po is the translation catalog for that document in the XX language. Documentation authors will mostly be concerned with master.doc (which can be a manpage, an XML document, an AsciiDoc file, etc); the translators will be mostly concerned with the PO file, while the end users will only see the XX.doc file.

Transitions with square brackets such as "[po4a updates po]" represent the execution of a po4a tool while transitions with curly brackets such as "{update of master.doc}" represent a manual modification of the project's files.

```
                                   master.doc
                                       |
                                       V
     +<-----<----+<-----<-----<--------+------->-------->-------+
     :           |                     |                        :
{translation}    |          {update of master.doc}              :
     :           |                     |                        :
   XX.doc        |                     V                        V
 (optional)      |                 master.doc ->-------->------>+
     :           |                   (new)                      |
     V           V                     |                        |
  [po4a-gettextize]   doc.XX.po -->+   |                        |
          |            (old)       |   |                        |
          |              ^         V   V                        |
          |              |   [po4a updates po]                  |
          V              |           |                          V
   translation.pot       ^           V                          |
          |              |        doc.XX.po                     |
          |              |         (fuzzy)                      |
    {translation}        |           |                          |
          |              ^           V                          V
          |              |     {manual editing}                 |
          |              |           |                          |
          V              |           V                          V
      doc.XX.po --->---->+<---<-- doc.XX.po    addendum     master.doc
      (initial)                 (up-to-date)  (optional)   (up-to-date)
          :                          |            |             |
          :                          V            |             |
          +----->----->----->------> +            |             |
                                     |            |             |
                                     V            V             V
                                     +------>-----+------<------+
                                                  |
                                                  V
                                     [po4a updates translations]
                                                  |
                                                  V
                                                XX.doc
                                             (up-to-date)
```

Again, this schema is overly complicated. Check on po4a(1) for a simplified overview.

The left part depicts how po4a-gettextize(1) can be used to convert an existing translation project to the po4a infrastructure. This script takes an original document and its translated counterpart, and tries to build the corresponding PO file. Such manual conversion is rather cumbersome (see the po4a-gettextize(1) documentation for more details), but it is only needed once to convert your existing translations. If you don't have any translation to convert, you can forget about this and focus on the right part of the schema.

On the top right part, the action of the original author is depicted, updating the documentation. The middle right part depicts the automatic updates of translation files: the new material is extracted and compared against the exiting translation. The previous translation is used for the parts that didn't change, while partially modified parts are connected to the previous translation with a "fuzzy" marker indicating that the translation must be updated. New or heavily modified material is left untranslated.

Then, the manual editing block depicts the action of the translators, that modify the PO files to provide translations to every original string and paragraph. This can be done using either a specific editor such as the GNOME Translation Editor, KDE's Lokalize or poedit, or using an online localization platform such as weblate or pootle. The translation result is a set of PO files, one per language. Please refer to the gettext documentation for more details.

The bottom part of the figure shows how po4a creates a translated source document from the master.doc original document and the doc.XX.po translation catalog that was updated by the translators. The structure of the document is reused, while the original content is replaced by its translated counterpart. Optionally, an addendum can be used to add some extra text to the translation. This is often used to add the name of the translator to the final document. See below for details.

Upon invocation, po4a updates both the translation files and the translated documentation files automatically.

### Starting a new translation project
If you start from scratch, you just have to write a configuration file for po4a, and you are set. The relevant templates are created for the missing files, allowing your contributors to translate your project to their language. Please refer to po4a(1) for a quick start tutorial and for all details.

If you have an existing translation, i.e. a documentation file that was translated manually, you can integrate its content in your po4a workflow using po4a-gettextize. This task is a bit cumbersome (as described in the tool's manpage), but once your project is converted to po4a workflow, everything will be updated automatically.

### Updating the translations and documents
Once setup, invoking po4a is enough to update both the translation PO files and translated documents. You may pass the "--no-translations" to po4a to not update the translations (thus only updating the PO files) or "--no-update" to not update the PO files (thus only updating the translations). This roughly corresponds to the individual po4a-updatepo and po4a-translate scripts which are now deprecated (see "Why are the individual scripts deprecated" in the FAQ below).

### Using addenda to add extra text to translations
Adding new text to the translation is probably the only thing that is easier in the long run when you translate files manually :). This happens when you want to add an extra section to the translated document, not corresponding to any content in the original document. The classical use case is to give credits to the translation team, and to indicate how to report translation-specific issues.

With po4a, you have to specify addendum files, that can be conceptually viewed as patches applied to the localized document after processing. Each addendum must be provided as a separate file, which format is however very different from the classical patches. The first line is a header line, defining the insertion point of the addendum (with an unfortunately cryptic syntax -- see below) while the rest of the file is added verbatim at the determined position.

The header line must begin with the string PO4A-HEADER:, followed by a semi-colon separated list of key=value fields.

For example, the following header declares an addendum that must be placed at the very end of the translation.

```
 PO4A-HEADER: mode=eof
```

Things are more complex when you want to add your extra content in the middle of the document. The following header declares an addendum that must be placed after the XML section containing the string "About this document" in translation.

```
 PO4A-HEADER: position=About this document; mode=after; endboundary=</section>
```

In practice, when trying to apply an addendum, po4a searches for the first line matching the "position" argument (this can be a regexp). Do not forget that po4a considers the translated document here. This documentation is in English, but your line should probably read as follows if you intend your addendum to apply to the French translation of the document.

```
 PO4A-HEADER: position=À propos de ce document; mode=after; endboundary=</section>
```

Once the "position" is found in the target document, po4a searches for the next line after the "position" that matches the provided "endboundary". The addendum is added right after that line (because we provided an endboundary, i.e. a boundary ending the current section).

The exact same effect could be obtained with the following header, that is equivalent:

```
 PO4A-HEADER: position=About this document; mode=after; beginboundary=<section>
```

Here, po4a searches for the first line matching "<section>" after the line matching "About this document" in the translation, and add the addendum before that line since we provided a beginboundary, i.e. a boundary marking the beginning of the next section. So this header line requires placing the addendum after the section containing "About this document", and instruct po4a that a section starts with a line containing the "<section>" tag. This is equivalent to the previous example because what you really want is to add this addendum either after "</section>" or before "<section>".

You can also set the insertion mode to the value "before", with a similar semantic: combining "mode=before" with an "endboundary" will put the addendum just after the matched boundary, that is the last potential boundary line before the "position". Combining "mode=before" with an "beginboundary" will put the addendum just before the matched boundary, that is the last potential boundary line before the "position".

```
  Mode   | Boundary kind |     Used boundary      | Insertion point compared to the boundary
 ========|===============|========================|=========================================
 'before'| 'endboundary' | last before 'position' | Right after the selected boundary
 'before'|'beginboundary'| last before 'position' | Right before the selected boundary
 'after' | 'endboundary' | first after 'position' | Right after the selected boundary
 'after' |'beginboundary'| first after 'position' | Right before the selected boundary
 'eof'   |   (none)      |  n/a                   | End of file
```

Hint and tricks about addenda

- Remember that these are regexp. For example, if you want to match the end of a nroff section ending with the line ".fi", do not use ".fi" as endboundary, because it will match with "the[ fi]le", which is obviously not what you expect. The correct endboundary in that case is: "^\.fi$".

- White spaces ARE important in the content of the "position" and boundaries. So the two following lines are different. The second one will only be found if there is enough trailing spaces in the translated document.

```
 PO4A-HEADER: position=About this document; mode=after; beginboundary=<section>
 PO4A-HEADER: position=About this document ; mode=after; beginboundary=<section>

```

- Although this context search may be considered to operate roughly on each line of the translated document, it actually operates on the internal data string of the translated document. This internal data string may be a text spanning a paragraph containing multiple lines or may be a XML tag itself alone. The exact insertion point of the addendum must be before or after the internal data string and can not be within the internal data string.

- Pass the "-vv" argument to po4a to understand how the addenda are added to the translation. It may also help to run po4a in debug mode to see the actual internal data string when your addendum does not apply.

Addenda examples

- If you want to add something after the following nroff section:

```
  .SH "AUTHORS"

```

You should select a two-step approach by setting mode=after. Then you should narrow down search to the line after AUTHORS with the position argument regex. Then, you should match the beginning of the next section (i.e., ^\.SH) with the beginboundary argument regex. That is to say:

```
 PO4A-HEADER:mode=after;position=AUTHORS;beginboundary=\.SH

```

- If you want to add something right after a given line (e.g. after the line "Copyright Big Dude"), use a position matching this line, mode=after and give a beginboundary matching any line.

```
 PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^

```

- If you want to add something at the end of the document, give a position matching any line of your document (but only one line. Po4a won't proceed if it's not unique), and give an endboundary matching nothing. Don't use simple strings here like "EOF", but prefer those which have less chance to be in your document.

```
 PO4A-HEADER:mode=after;position=About this document;beginboundary=FakePo4aBoundary

```

More detailed example

Original document (POD formatted):

```
 |=head1 NAME
 |
 |dummy - a dummy program
 |
 |=head1 AUTHOR
 |
 |me
```

Then, the following addendum will ensure that a section (in French) about the translator is added at the end of the file (in French, "TRADUCTEUR" means "TRANSLATOR", and "moi" means "me").

```
 |PO4A-HEADER:mode=after;position=AUTEUR;beginboundary=^=head
 |
 |=head1 TRADUCTEUR
 |
 |moi
 |
```

To put your addendum before the AUTHOR, use the following header:

```
 PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1
```

This works because the next line matching the beginboundary "/^=head1/" after the section "NAME" (translated to "NOM" in French), is the one declaring the authors. So, the addendum will be put between both sections. Note that if another section is added between NAME and AUTHOR sections later, po4a will wrongfully put the addenda before the new section.

To avoid this you may accomplish the same using mode=before:

```
 PO4A-HEADER:mode=before;position=^=head1 AUTEUR
```

## How does it work?
This chapter gives you a brief overview of the po4a internals, so that you may feel more confident to help us to maintain and to improve it. It may also help you to understand why it does not do what you expected, and how to solve your problems.

### TransTractors and project architecture
At the core of the po4a project, the Locale::Po4a::TransTractor(3pm) class is the common ancestor to all po4a parsers. This strange name comes from the fact that it is at the same time in charge of translating document and extracting strings.

More formally, it takes a document to translate plus a PO file containing the translations to use as input while producing two separate outputs: Another PO file (resulting of the extraction of translatable strings from the input document), and a translated document (with the same structure as the input one, but with all translatable strings replaced with content of the input PO). Here is a graphical representation of this:

```
   Input document --\                             /---> Output document
                     \      TransTractor::       /       (translated)
                      +-->--   parse()  --------+
                     /                           \
   Input PO --------/                             \---> Output PO
                                                       (extracted)
```

This little bone is the core of all the po4a architecture. If you provide both input and disregard the output PO, you get po4a-translate. If you disregard the output document instead, you get po4a-updatepo. The po4a uses a first TransTractor to get an up-to-date output POT file (disregarding the output documents), calls msgmerge -U to update the translation PO files on disk, and builds a second TransTractor with these updated PO files to update the output documents. In short, po4a provides one-stop solution to update what needs to be, using a single configuration file.

po4a-gettextize also uses two TransTractors, but another way: It builds one TransTractor per language, and then build a new PO file using the msgids of the original document as msgids, and the msgids of the translated document as msgstrs. Much care is needed to ensure that the strings matched this way actually match, as described in po4a-gettextize(1).

### Format-specific parsers
All po4a format parsers are implemented on top of the TransTractor. Some of them are very simple, such as the Text, Markdown and AsciiDoc ones. They load the lines one by one using TransTractor::shiftline(), accumulate the paragraphs' content or whatever. Once a string is completely parsed, the parser uses TransTractor::translate() to (1) add this string to the output PO file and (2) get the translation from the input PO file. The parser then pushes the result to the output file using TransTractor::pushline().

Some other parsers are more complex because they rely on an external parser to analyze the input document. The Xml, HTML, SGML and Pod parsers are built on top of SAX parsers. They declare callbacks to events such as "I found a new title which content is the following" to update the output document and output POT files according to the input content using TransTractor::translate() and TransTractor::pushline(). The Yaml parser is similar but different: it serializes a data structure produced by the YAML::Tiny parser. This is why the Yaml module of po4a fails to declare the reference lines: the location of each string in the input file is not kept by the parser, so we can only provide "$filename:1" as a string location. The SAX-oriented parsers use globals and other tricks to save the file name and line numbers of references.

One specific issue arises from file encodings and BOM markers. Simple parsers can forget about this issue, that is handled by TransTractor::read() (used internally to get the lines of an input document), but the modules relying on an external parser must ensure that all files are read with an appropriate PerlIO decoding layer. The easiest is to open the file yourself, and provide an filehandle or directly the full string to your external parser. Check on Pod::read() and Pod::parse() for an example. The content read by the TransTractor is ignored, but a fresh filehandle is passed to the external parser. The important part is the "<:encoding($charset)" mode that is passed to the open() perl function.

### Po objects
The Locale::Po4a::Po(3pm) class is in charge of loading and using PO and POT files. Basically, you can read a file, add entries, get translations with the gettext() method, write the PO into a file. More advanced features such as merging a PO file against a POT file or validating a file are delegated to msgmerge and msgfmt respectively.

### Contributing to po4a
Even if you have never contributed to any Open Source project in the past, you are welcome: we are willing to help and mentor you here. po4a is best maintained by its users nowadays. As we lack manpower, we try to make the project welcoming by improving the doc and the automatic tests to make you confident in contributing to the project. Please refer to the CONTRIBUTING.md file for more details.

## Open-source projects using po4a
Here is a very partial list of projects that use po4a in production for their documentation. If you want to add your project to the list, just drop us an email (or a Merge Request).

- adduser (man): users and groups management tool.

- apt (man, docbook): Debian package manager.

- aptitude (docbook, svg): terminal-based package manager for Debian

- F-Droid website <https://gitlab.com/fdroid/fdroid-website> (markdown): installable catalog of FOSS (Free and Open Source Software) applications for the Android platform.

- git <https://github.com/jnavila/git-manpages-l10n> (asciidoc): distributed version-control system for tracking changes in source code.

- Linux manpages <https://salsa.debian.org/manpages-l10n-team/manpages-l10n> (man) This project provides an infrastructure for translating many manpages to different languages, ready for integration into several major distributions (Arch Linux, Debian and derivatives, Fedora).

- Stellarium <https://github.com/Stellarium/stellarium> (HTML): a free open source planetarium for your computer. po4a is used to translate the sky culture descriptions.

- Jamulus <https://jamulus.io/> (markdown, yaml, HTML): a FOSS application for online jamming in real time. The website documentation is maintained in multiple languages using po4a.

- Other item to sort out: <https://gitlab.com/fdroid/fdroid-website/> <https://github.com/fsfe/reuse-docs/pull/61>

## FAQ

### How do you pronounce po4a?
I personally vocalize it as pouah <https://en.wiktionary.org/wiki/pouah>, which is a French onomatopoetic that we use in place of yuck :) I may have a strange sense of humor :)

### Why are the individual scripts deprecated?
Indeed, po4a-updatepo and po4a-translate are deprecated in favor of po4a. The reason is that while po4a can be used as a drop-in replacement to these scripts, there is quite a lot of code duplication here. Individual scripts last around 150 lines of codes while the po4a program lasts 1200 lines, so they do a lot in addition of the common internals. The code duplication results in bugs occurring in both versions and needing two fixes. One example of such duplication are the bugs #1022216 in Debian and the issue #442 in GitHub that had the exact same fix, but one in po4a and the other po4a-updatepo.

In the long run, I would like to drop the individual scripts and only maintain one version of this code. The sure thing is that the individual scripts will not get improved anymore, so only po4a will get the new features. That being said, there is no deprecation urgency. I plan to keep the individual scripts as long as possible, and at least until 2030. If your project still use po4a-updatepo and po4a-translate in 2030, you may have a problem.

We may also remove the deprecation of these scripts at some point, if a refactoring reduces the code duplication to zero. If you have an idea (or better: a patch), your help is welcome.

### What about the other translation tools for documentation using gettext?
There are a few of them. Here is a possibly incomplete list, and more tools are coming at the horizon.

poxml

This is the tool developed by KDE people to handle DocBook XML. AFAIK, it was the first program to extract strings to translate from documentation to PO files, and inject them back after translation. It can only handle XML, and only a particular DTD. I'm quite unhappy with the handling of lists, which end in one big msgid. When the list become big, the chunk becomes harder to swallow.

po-debiandoc

This program done by Denis Barbier is a sort of precursor of the po4a SGML module, which more or less deprecates it. As the name says, it handles only the DebianDoc DTD, which is more or less a deprecated DTD.

xml2po.py

Used by the GIMP Documentation Team since 2004, works quite well even if, as the name suggests, only with XML files and needs specially configured makefiles.

Sphinx

The Sphinx Documentation Project also uses gettext extensively to manage its translations. Unfortunately, it works only for a few text formats, rest and markdown, although it is perhaps the only tool that does this managing the whole translation process.

The main advantages of po4a over them are the ease of extra content addition (which is even worse there) and the ability to achieve gettextization.

### SUMMARY of the advantages of the gettext based approach

- The translations are not stored along with the original, which makes it possible to detect if translations become out of date.

- The translations are stored in separate files from each other, which prevents translators of different languages from interfering, both when submitting their patch and at the file encoding level.

- It is based internally on gettext (but po4a offers a very simple interface so that you don't need to understand the internals to use it). That way, we don't have to re-implement the wheel, and because of their wide use, we can think that these tools are more or less bug free.

- Nothing changed for the end-user (beside the fact translations will hopefully be better maintained). The resulting documentation file distributed is exactly the same.

- No need for translators to learn a new file syntax and their favorite PO file editor (like Emacs' PO mode, Lokalize or Gtranslator) will work just fine.

- gettext offers a simple way to get statistics about what is done, what should be reviewed and updated, and what is still to do. Some example can be found at those addresses:

```
 - https://docs.kde.org/stable5/en/kdesdk/lokalize/project-view.html
 - http://www.debian.org/intl/l10n/

```

But everything isn't green, and this approach also has some disadvantages we have to deal with.

- Addenda are somewhat strange at the first glance.

- You can't adapt the translated text to your preferences, like splitting a paragraph here, and joining two other ones there. But in some sense, if there is an issue with the original, it should be reported as a bug anyway.

- Even with an easy interface, it remains a new tool people have to learn. One of my dreams would be to integrate somehow po4a to Gtranslator or Lokalize. When a documentation file is opened, the strings are automatically extracted, and a translated file + po file can be written to disk. If we manage to do an MS Word (TM) module (or at least RTF) professional translators may even use it.

## SEE ALSO

- The documentation of the all-in-one tool that you should use: po4a(1).

- The documentation of the individual po4a scripts: po4a-gettextize(1), po4a-updatepo(1), po4a-translate(1), po4a-normalize(1).

- The additional helping scripts: msguntypot(1), po4a-display-man(1), po4a-display-pod(1).

- The parsers of each formats, in particular to see the options accepted by each of them: Locale::Po4a::AsciiDoc(3pm) Locale::Po4a::Dia(3pm), Locale::Po4a::Gemtext(3pm), Locale::Po4a::Guide(3pm), Locale::Po4a::Ini(3pm), Locale::Po4a::KernelHelp(3pm), Locale::Po4a::Man(3pm), Locale::Po4a::RubyDoc(3pm), Locale::Po4a::Texinfo(3pm), Locale::Po4a::Text(3pm), Locale::Po4a::Xhtml(3pm), Locale::Po4a::Yaml(3pm), Locale::Po4a::BibTeX(3pm), Locale::Po4a::Docbook(3pm), Locale::Po4a::Halibut(3pm), Locale::Po4a::LaTeX(3pm), Locale::Po4a::Org(3pm), Locale::Po4a::Pod(3pm), Locale::Po4a::SimplePod(3pm), Locale::Po4a::Sgml(3pm), Locale::Po4a::TeX(3pm), Locale::Po4a::VimHelp, Locale::Po4a::Wml(3pm), Locale::Po4a::Xml(3pm).

- The implementation of the core infrastructure: Locale::Po4a::TransTractor(3pm) (particularly important to understand the code organization), Locale::Po4a::Chooser(3pm), Locale::Po4a::Po(3pm), Locale::Po4a::Common(3pm). Please also check the CONTRIBUTING.md file in the source tree.

## AUTHORS

```
 Denis Barbier <barbier,linuxfr.org>
 Martin Quinson (mquinson#debian.org)
```


podman-rootless

package: podman

title: podman-rootless(7)

text:
# podman-rootless(7)

## Shortcomings of Rootless Podman
The following list categorizes the known issues and irregularities with running Podman as a non-root user. Although currently functional, there is still a number of work items that are under consideration to be added. These proposed changes are in varying degrees of design and development.

Contributors are more than welcomed to help with this work. If you decide to carve off a piece and work on it, please create an issue in GitHub, and assign it to yourself. If you find other unexpected behavior with rootless Podman and feel it’s warranted, please feel free to update this document.

•

Podman can not create containers that bind to ports < 1024.

- The kernel does not allow processes without CAP_NET_BIND_SERVICE to bind to low ports.

- You can modify the net.ipv4.ip_unprivileged_port_start sysctl to change the lowest port. For example sysctl net.ipv4.ip_unprivileged_port_start=443 allows rootless Podman containers to bind to ports >= 443.

- A proxy server, kernel firewall rule, or redirection tool such as redir may be used to redirect traffic from a privileged port to an unprivileged one (where a podman pod is bound) in a server scenario - where a user has access to the root account (or setuid on the binary would be an acceptable risk), but wants to run the containers as an unprivileged user for enhanced security and for a limited number of pre-known ports.

•

As of Podman 5.0, pasta is the default networking tool. Since pasta copies the IP address of the main interface, connections to that IP from containers do not work. This means that unless you have more than one interface, inter-container connections cannot be made without explicitly passing a pasta network configuration, either in containers.conf or at runtime.

•

If you previously had port forwards (ex. via -p 80:80) that other containers could access, you can either revert back to slirp4netns or use the solution (setting pasta options with 10.0.2.x IPs) posted here.

- “How To” documentation is patchy at best.

- If /etc/subuid and /etc/subgid are not set up for a user, then podman commands can easily fail

- This can be a big issue on machines using Network Based Password information (FreeIPA, Active Directory, LDAP)

- We are working to get support for NSSWITCH on the /etc/subuid and /etc/subgid files.

•

No cgroup V1 Support

- cgroup V1 does not safely support cgroup delegation.

- As of Fedora 31 defaults to cgroup V2, which has full support of rootless cgroup management. Note this requires the --cgroup-manager within rootless containers to use systemd, which new containers will get by default.

•

Some system unit configuration options do not work in the rootless container

- systemd fails to apply several options and failures are silently ignored (e.g. CPUShares, MemoryLimit). Should work on cgroup V2.

- Use of certain options will cause service startup failures (e.g. PrivateNetwork). The systemd services requiring PrivateNetwork can be made to work by passing --cap-add SYS_ADMIN, but the security implications should be carefully evaluated. In most cases, it's better to create an override.conf drop-in that sets PrivateNetwork=no. This also applies to containers run by root.

- Can not share container images with CRI-O or other rootful users

- Difficult to use additional stores for sharing content

- Does not work on NFS or parallel filesystem homedirs (e.g. GPFS)

- NFS and parallel filesystems enforce file creation on different UIDs on the server side and does not understand User Namespace.

- When a container root process like YUM attempts to create a file owned by a different UID, NFS Server/GPFS denies the creation.

•

Does not work with homedirs mounted with noexec/nodev

•

User can set up storage to point to other directories they can write to that are not mounted noexec/nodev

•

Support for using native overlayfs as an unprivileged user is only available for Podman version >= 3.1 on a Linux kernel version >= 5.12, otherwise the slower fuse-overlayfs may be used.

•

A few Linux distributions (e.g. Ubuntu) have supported even older Podman and Linux kernel versions by modifying the normal Linux kernel behaviour.

- Only other supported driver is VFS.

- Cannot use ping out of the box.

•

(Can be fixed by setting sysctl on host)

- Requires new shadow-utils (not found in older (RHEL7/Centos7 distros) Should be fixed in RHEL7.7 release)

- A few commands do not work.

•

mount/unmount (on fuse-overlay)

•

Only works if you enter the mount namespace with podman unshare

- podman stats (Works with cgroup V2 support)

- Checkpoint and Restore (CRIU requires root)

- Pause and Unpause (Works with cgroup V2 support)

•

Issues with higher UIDs can cause builds to fail

•

If a build is attempting to use a UID that is not mapped into the user namespace mapping for a container, then builds will not be able to put the UID in an image.

•

Making device nodes within a container fails, even when running --privileged.

•

The kernel does not allow non root user processes (processes without CAP_MKNOD) to create device nodes. If a container needs to create device nodes, it must be run as root.

•

When using --net=host with rootless containers, subsequent podman execs to that container will not join the host network namespace because it is owned by root.