On launch s2p can either be configured with command line options or with properties and property files. When running s2p as a system service /etc/s2p.conf contains the complete configuration. Settings in files and command line options (the s2p manpage explains all available options) can be mixed. A command line option overwrites the respective 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 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 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. You can query the current s2p settings with the SCSI Control app or with s2pctl -P. The data displayed by s2pctl can directly be used for creating property files, e.g. in /etc/s2p.conf.

Device Definitions

For the system service or as an alternative to the command line emulated devices can 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 Caching algorithm PiSCSI compatible --caching-mode/-m
name Device name for the INQUIRY command Depends on the device type,
usually "SCSI2Pi" with version number
params Device parameters (key=value) or
name of the image file, resp.
Depends on the device type
scsi_level SCSI level according to specification Depends on the device type and the image file extension --scsi-level
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.
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.