On launch s2p can either be configured with command line options or with properties and property files.
When there are a lot of startup parameters using property files is more convenient than providing a long parameter list. Settings in files and command line options (the s2p manpage explains all available options) can be mixed. A command line option overwrites the corrsponding setting in a property file. Mode page definitions are only possible with properties.
Unless explicitly specified with the -C option s2p uses the /etc/s2p.conf and ~/.config/s2p.conf as default property files. These files are optional. When you explicitly specify a property file, this file must exist, though. You can provide several property files as a comma-separated list (e.g. one file per device). Property file lines starting with a '#' are treated as comments.
Single properties are defined with the command line option -c:

>s2p -c log_level=trace -c reserved_ids=6

Property overview

The following table lists the properties supported by s2p. If there is a corresponding command line option it is also listed.

Name Description Default Command Line Option
device Device definition, see below for details --sasi-id/-h, --scsi-id/-i
extensions SCSI2Pi 3.0: Mapping of file extensions to device types
image_folder Default folder for image files ~/images --image-folder/-F
locale Language for error and status messages System setting --locale/-z
log_level s2p log level info --log-level/-L
log_pattern/td> SCSI2Pi 3.0: s2p log pattern,
see the spdlog website for details
spdlog default setting --log-pattern/-l
mode_page Mode page definition, see below for details Predefined s2p default mode pages
port s2p server port 6868 --port/-p
reserved_ids Comma-separated list of reserved IDs --reserved-ids/-r
scan_depth Maximum depth of the folders for image files 1 --scan-depth/-R
token_file File with access token --token-file/-P

When launching s2p the effective properties are listed when logging on trace level. The effective properties consist of the data from the property files and the command line parameters. Command line settings have a higher priority than properties in property files.
With upcoming versions you can retrieve the current s2p settings with s2pctl -P. This information can directly be used for creating property files, e.g. as /etc/s2p.conf when using s2p as system service.

Device Definitions

As an alternative to the command line emulated devices can also be defined in a property file. The following properties are supported:

Name Description Default Command Line Option
active If false the device will not be used true
block_size Sector size SCSI hard drives: 512 bytes,
SASI hard drives: 256 bytes,
CD-ROM and MO drives: 2048 bytes
caching_mode SCSI2Pi 3.0: Caching algorithm PiSCSI compatible --caching-mode/-m
scsi_level SCSI2PI 3.0: SCSI level according to specification Depends on the device type and the image file extension --scsi-level
params Device parameters (key=value) or
name of the image file, resp.
Depends on the device type
type Device type Derived from the image file extension, if possible --type/-t

Example for the contents of a property file:

# ID 0: SCSI drive with standard parameters, image file is "test.hds"
# When the device type is missing it is derived from the extension of the image file
# ID 0, LUN 1: SCSI CD-ROM with a sector size of 512 bytes, image file is "test.iso"

Mode pages

Mode pages define some of the properties of a SCSI device. Some drivers query these data and sometimes expect them to have certain values. Depending on the device type SCSI2Pi has a set of predefined mode pages (1, 2, 3, 4, 7, 8, 10, 12, 13, 32, 37, 48). These are compatible with the vast majority of device drivers. There are rare cases, usually with rather exotic computers, where the default data may not be what a driver is expecting. It can also happen that a driver expects a mode page which is not covered by the pages predefined by s2p. In such cases configuring mode pages with custom data helps. You need to know, though, which page data the affected driver expects.
With the -I option the s2pdump tool creates mode page definitions from the data returned by a real device.

The data s2p returns for a mode page are defined with the mode_page property key:

# Page 0 for all drives with the vendor ID "IBM"
# Page 3 for all drives with the vendor ID "SCSI2Pi" and the product name "SCSI HD 1011 MiB"
mode_page.3.SCSI2Pi:SCSI HD 1011 MiB=03:05:0a:0c:b0:b4:de
# For FUJITSU drives remove page 4 from the set of predefined pages
# This page definition is invalid because the page code has an inconsistent value
# This page definition is invalid because the length field has a wrong value

The mode_page keyword is followed by the page code. If the page code is identical with a predefined page, the custom page replaces the predefined page, i.e. you can overwrite any s2p default page. Otherwise the new page is added to the list of existing mode pages. The last key components are the vendor and product name of the INQUIRY string of the device the custom mode page shall be used for. The product name field is optional. The actual page data are hexadecimal bytes and can optionally be separated by a colon. When a page definition does not contain any data this page is removed from the list of predefined pages. Use this syntax when you encounter a driver that expects one of the default mode pages not to be present.
The property value contains the complete data of the page specified in the key. s2p checks page code and length of a custom mode page for compliance with the SCSI specification. Only for page 0 there is no length validation because this page does not have a well-defined format.