package piscsi_interface

Get desktop application:
View/edit binary Protocol Buffers messages

Commands piscsi can execute and their parameters

• PbOperation operation = 1

• repeated PbDeviceDefinition devices = 2

  The non-empty list of devices for this command

• map<string, string> params = 3

  The named parameters for the operation, e.g. a filename, or a network interface list

The device data, sent from the server to the client

Used in: PbDevicesInfo

• int32 id = 1

• int32 unit = 2

• PbDeviceType type = 3

• optional PbDeviceProperties properties = 4

• optional PbDeviceStatus status = 5

• optional PbImageFile file = 6

  Image file information, if the device supports image files

• map<string, string> params = 7

  Effective parameters the device was created with

• string vendor = 8

• string product = 9

• string revision = 10

• int32 block_size = 11

  Block size in bytes

• uint64 block_count = 12

  Number of blocks

The device definition, sent from the client to the server

Used in: PbCommand

• int32 id = 1

• int32 unit = 2

• PbDeviceType type = 3

• map<string, string> params = 4

  Device specific named parameters, e.g. the name of an image file

• int32 block_size = 5

  The optional block size in bytes per sector, must be one of the supported block sizes

• string vendor = 6

  The device name components

• string product = 7

• string revision = 8

• bool protected = 9

  Create a write-protected device

The properties supported by a device

Used in: PbDevice, PbDeviceTypeProperties

• bool read_only = 1

  Read-only media (e.g. CD-ROMs) are not protectable but permanently read-only

• bool protectable = 2

  Medium can be write-protected

• bool stoppable = 3

  Device can be stopped, e.g. parked

• bool removable = 4

  Medium can be removed

• bool lockable = 5

  Medium can be locked

• bool supports_file = 6

  Device supports image file as a parameter

• bool supports_params = 7

  Device supports parameters other than a filename

• map<string, string> default_params = 8

  List of default parameters, if any (requires supports_params to be true)

• int32 luns = 9

  LUN numbers this device can have, usually 32

• repeated uint32 block_sizes = 10

  Unordered list of permitted block sizes in bytes, empty if the block size is not configurable

The status of a device, only meaningful if the respective feature is supported

Used in: PbDevice

• bool protected = 1

  Medium is write-protected

• bool stopped = 2

  Device is stopped, e.g. parked

• bool removed = 3

  Medium is removed

• bool locked = 4

  Medium is locked

The available device types

Used in: PbDevice, PbDeviceDefinition, PbDeviceTypeProperties, PbImageFile, PbMappingInfo

• UNDEFINED = 0

• SAHD = 1

  Non-removable SASI drive, not supported anymore but must not be removed because of backwards compatibility

• SCHD = 2

  Non-removable SCSI drive

• SCRM = 3

  Removable SCSI drive

• SCMO = 4

  Magnoto-Optical drive

• SCCD = 5

  CD-ROM drive

• SCBR = 6

  Network bridge

• SCDP = 7

  DaynaPort network adapter

• SCHS = 8

  Host services device

• SCLP = 9

  Printer device

Device properties by device type. (Note that a protobuf map cannot be used because enums cannot be map keys.)

Used in: PbDeviceTypesInfo

• PbDeviceType type = 1

• optional PbDeviceProperties properties = 2

Used in: PbResult, PbServerInfo

• repeated PbDeviceTypeProperties properties = 1

Used in: PbResult, PbServerInfo

• repeated PbDevice devices = 1

piscsi special purpose error codes for cases where a textual error message may not be not sufficient. The client may react on this code, e.g. by prompting the user for an authentication token.

Used in: PbResult

• NO_ERROR_CODE = 0

  No error code available

• UNKNOWN_OPERATION = 1

  The client sent an operation code not supported by this server

• UNAUTHORIZED = 2

  Authentication/Authorization error

The image file data

Used in: PbDevice, PbImageFilesInfo, PbResult

• string name = 1

• PbDeviceType type = 2

  The assumed device type, based on the filename extension

• uint64 size = 3

  The file size in bytes, 0 for block devices in /dev

• bool read_only = 4

The default image folder and the image files it contains

Used in: PbResult, PbServerInfo

• string default_image_folder = 1

• repeated PbImageFile image_files = 2

• int32 depth = 3

  The maximum nesting depth, configured with the -R option

Log level information

Used in: PbResult, PbServerInfo

• repeated string log_levels = 2

  List of available log levels, ordered by increasing by severity

• string current_log_level = 3

The supported file extensions mapped to their respective device types

Used in: PbResult, PbServerInfo

• map<string, PbDeviceType> mapping = 1

The network interfaces information

Used in: PbResult, PbServerInfo

• repeated string name = 1

piscsi remote operations, returning PbResult

Used in: PbCommand

• NO_OPERATION = 0

• ATTACH = 1

  Attach devices and return the new device list (PbDevicesInfo) Parameters (depending on the device type): "file": The filename relative to the default image folder "interface": A prioritized comma-separated list of interfaces to create a network bridge for "inet": The IP address and netmask for the network bridge "cmd": The command to be used for printing, with "%f" as file placeholder

• DETACH = 2

  Detach a device and return the new device list (PbDevicesInfo) Detaches all LUNs of that device which are equal to or higher than the LUN specified.

• DETACH_ALL = 3

  Detach all devices, does not require a device list

• START = 4

  Start device

• STOP = 5

  Stop device, e.g. park drive

• INSERT = 6

  Insert medium Parameters: "file": The filename, relative to the default image folder

• EJECT = 7

  Eject medium

• PROTECT = 8

  Write-protect medium (not possible for read-only media)

• UNPROTECT = 9

  Make medium writable (not possible for read-only media)

• SERVER_INFO = 10

  Gets the server information (PbServerInfo). Calling this operation without a list of operations should be avoided because this may return a lot of data. More specific other operations should be used instead. Parameters: "operations": Optional case insensitive comma-separated list of operation names to return data for, e.g. "version_info,log_level_info". Unknown operation names are ignored. If this parameter is missing the full set of data supported by PbServerInfo is returned. "folder_pattern": Optional filter, only folder names containing the case-insensitive pattern are returned "file_pattern": Optional filter, only filenames containing the case-insensitive pattern are returned

• VERSION_INFO = 11

  Get piscsi server version (PbVersionInfo)

• DEVICES_INFO = 12

  Get information on attached devices (PbDevicesInfo) Returns data for all attached devices if the device list is empty.

• DEVICE_TYPES_INFO = 13

  Get device properties by device type (PbDeviceTypesInfo)

• DEFAULT_IMAGE_FILES_INFO = 14

  Get information on available image files in the default image folder (PbImageFilesInfo) Parameters: "folder_pattern": Optional filter, only folder names containing the case-insensitive pattern are returned "file_pattern": Optional filter, only filenames containing the case-insensitive pattern are returned

• IMAGE_FILE_INFO = 15

  Get information on an image file (not necessarily in the default image folder). Parameters: "file": The filename. Either an absolute path or a path relative to the default image folder.

• LOG_LEVEL_INFO = 16

  Get information on the available log levels and the current log level (PbLogLevelInfo)

• NETWORK_INTERFACES_INFO = 17

  Get the names of the available network interfaces (PbNetworkInterfacesInfo) Only lists interfaces that are up.

• MAPPING_INFO = 18

  Get the mapping of extensions to device types (PbMappingInfo)

• RESERVED_IDS_INFO = 19

  Get the list of reserved device IDs (PbReservedIdsInfo)

• DEFAULT_FOLDER = 20

  Set the default folder for image files. This folder must be located in /home. Parameters: "folder": The path of the default folder, relative to the user's home folder if relative.

• LOG_LEVEL = 21

  Set the log level. Parameters: "level": The new log level

• RESERVE_IDS = 22

  Block IDs from being used, usually the IDs of the initiators (computers) in the SCSI chain. Parameters: "ids": A comma-separated list of IDs to reserve, or an empty string in order not to reserve any ID.

• SHUT_DOWN = 23

  Shut down the piscsi process or shut down/reboot the Pi Parameters: "mode": The shutdown mode, one of "rascsi": Shuts down the piscsi process ("rascsi" instead of "piscsi" for backwards compatibility) "system": Shuts down the Pi "reboot": Reboots the Pi

• CREATE_IMAGE = 24

  Create an image file. The image file must not yet exist. Parameters: "file": The filename, relative to the default image folder "size": The file size in bytes, must be a multiple of 512 "read_only": Optional, "true" (case-insensitive) in order to create a read-only file

• DELETE_IMAGE = 25

  Delete an image file. Parameters: "file": The filename, relative to the default image folder.

• RENAME_IMAGE = 26

  Rename/Move an image file. Parameters: "from": The old filename, relative to the default image folder "to": The new filename, relative to the default image folder The new filename must not yet exist.

• COPY_IMAGE = 27

  Copy an image file. Parameters: "from": The source filename, relative to the default image folder "to": The destination filename, relative to the default image folder "read_only": Optional, "true" (case-insensitive) in order to create a read-only file The destination filename must not yet exist.

• PROTECT_IMAGE = 28

  Write-protect an image file. Parameters: "file": The filename, relative to the default image folder

• UNPROTECT_IMAGE = 29

  Make an image file writable. Parameters: "file": The filename, relative to the default image folder

• CHECK_AUTHENTICATION = 30

  Check whether an authentication token is valid. A client can use this operation in order to find out whether piscsi authentication is enable or to use piscsi authentication for securing client-internal operations.

• OPERATION_INFO = 31

  Get operation meta data (PbOperationInfo)

• STATISTICS_INFO = 32

  Get statistics (PbStatisticsInfo)

Mapping of operations to their ordinals

Used in: PbResult, PbServerInfo

• map<int32, PbOperationMetaData> operations = 1

The list of parameters supported by an operation

Used in: PbOperationInfo

• string server_side_name = 1

  The operation name at the time the server-side protobuf code was generated.

• string description = 2

  Optional short description

• repeated PbOperationParameter parameters = 3

The operation parameter meta data. The parameter data type is provided by the protobuf API.

Used in: PbOperationMetaData

• string name = 1

• string description = 2

  Optional short description

• repeated string permitted_values = 3

  There is no specific set of permitted values if empty

• string default_value = 4

  Optional default value

• bool is_mandatory = 5

  True if this parameter is mandatory

The reserved device IDs

Used in: PbResult, PbServerInfo

• repeated int32 ids = 1

The result of a command

• bool status = 1

  false means that an error occurred

• string msg = 2

  An optional error or information message, depending on the status. A string without trailing CR/LF.

• PbErrorCode error_code = 14

  An optional error code. Only to be used in cases where textual information is not sufficient.

• oneof result

  Optional additional result data

  • PbServerInfo server_info = 3

    The result of a SERVER_INFO command

  • PbVersionInfo version_info = 4

    The result of a VERSION_INFO command

  • PbLogLevelInfo log_level_info = 5

    The result of a LOG_LEVEL_INFO command

  • PbDevicesInfo devices_info = 6

    The result of a DEVICES_INFO, ATTACH or DETACH command

  • PbDeviceTypesInfo device_types_info = 7

    The result of a DEVICE_TYPES_INFO command

  • PbImageFilesInfo image_files_info = 8

    The result of a DEFAULT_IMAGE_FILES_INFO command

  • PbImageFile image_file_info = 9

    The result of an IMAGE_FILE_INFO command

  • PbNetworkInterfacesInfo network_interfaces_info = 10

    The result of a NETWORK_INTERFACES_INFO command

  • PbMappingInfo mapping_info = 11

    The result of an MAPPING_INFO command

  • PbReservedIdsInfo reserved_ids_info = 12

    The result of a RESERVED_IDS_INFO command

  • PbOperationInfo operation_info = 13

    The result of an OPERATION_INFO command

  • PbStatisticsInfo statistics_info = 15

    The result of a STATISTICS_INFO command

The piscsi server information. All data can also be requested with individual commands.

Used in: PbResult

• optional PbVersionInfo version_info = 1

  The piscsi server version data

• optional PbLogLevelInfo log_level_info = 2

  The available log levels and the current log level

• optional PbDeviceTypesInfo device_types_info = 3

  Supported device types and their properties

• optional PbImageFilesInfo image_files_info = 4

  The image files in the default folder

• optional PbNetworkInterfacesInfo network_interfaces_info = 5

  The available (up) network interfaces

• optional PbMappingInfo mapping_info = 6

  The extensions to device types mapping

• optional PbReservedIdsInfo reserved_ids_info = 7

  The reserved device IDs

• optional PbDevicesInfo devices_info = 8

  The attached devices

• optional PbOperationInfo operation_info = 9

  The operation meta data

• optional PbStatisticsInfo statistics_info = 10

  The statistics

Used in: PbStatisticsInfo

• PbStatisticsCategory category = 1

• int32 id = 2

  The device ID and LUN for this statistics item. Both are -1 if the item is not device specific.

• int32 unit = 3

• string key = 4

  A symbolic unique item name, may be used for I18N. Supported values and their categories: "read_error_count" (ERROR, SCHD/SCRM/SCMO/SCCD) "write_error_count" (ERROR, SCHD/SCRM/SCMO) "cache_miss_read_count" (INFO, SCHD/SCRM/SCMO/SCCD) "cache_miss_write_count" (INFO, SCHD/SCRM/SCMO) "sector_read_count" (INFO, SCHD/SCRM/SCMO/SCCD) "sector_write_count" (INFO, SCHD/SCRM/SCMO) "byte_read_count" (INFO, SCDP) "byte_write_count" (INFO, SCDP) "print_error_count" (ERROR, SCLP) "print_warning_count" (WARNING, SCLP) "file_print_count" (INFO, SCLP) "byte_receive_count" (INFO, SCLP)

• uint64 value = 5

Statistics categories ordered by increasing severity

Used in: PbStatistics

• CATEGORY_NONE = 0

• CATEGORY_INFO = 1

• CATEGORY_WARNING = 2

• CATEGORY_ERROR = 3

The information on collected statistics

Used in: PbResult, PbServerInfo

• repeated PbStatistics statistics = 1

Piscsi server version information

Used in: PbResult, PbServerInfo

• int32 major_version = 1

  The piscsi version

• int32 minor_version = 2

• int32 patch_version = 3

  < 0 for a development version, = 0 if there is no patch yet