sbctl

package: sbctl

title: sbctl(8)

summary: Secure Boot Manager

text:
# sbctl(8)

## NAME
sbctl - Secure Boot Manager

## SYNOPSIS
sbctl <command>

## DESCRIPTION
sbctl is a tool that allows one to create keys for secure boot, securely enroll them and keep track of files to sign.

## EFI SIGNING COMMANDS
status

Shows the current secure boot status of the system. It checks if you are currently booted in UEFI with Secure Boot, and whether Setup Mode has been enabled.

create-keys

Creates a set of signing keys used to sign EFI binaries. Currently, it will create the following keys:

•Platform Key

•Key Exchange Key

•Signature Database Key -e, --export

The directory to persist the exported keys.

-d, --database-path

Path to save the GUID file when generating keys.

enroll-keys

Enrolls the created key into the EFI variables.

```
Note that some devices have hardware firmware that is signed and
validated when Secure Boot is enabled. Failing to validate this firmware
could brick devices. It's recommended to enroll your own keys with
Microsoft certificates.
```

-m, --microsoft

Enroll UEFI vendor certificates from Microsoft into the signature database. See Option ROM*.

-t, --tpm-eventlog

Enroll checksums from the TPM Eventlog into the signature database. See Option ROM*.

This feature is experimental

-c, --custom

Enroll custom KEK and db certificates from "/var/lib/sbctl/keys/custom/KEK/", "/var/lib/sbctl/keys/custom/db/", respectively.

-f, --firmware-builtin

Enroll signatures from dbDefault, KEKDefault or PKDefault. This is usefull if sbctl does not vendor your OEM certificates, or doesn’t include all of them. Valid values are "db", "KEK" or "PK" passed as a comma delimitered string.

Default: "db,KEK"

--yes-this-might-brick-my-machine, --yolo

Ignore the Option ROM error and continue enrolling keys into the UEFI firmware. See Option ROM*.

-i, --ignore-immutable

Ignore checking /sys/firmware/efi/efivars/ for immutable files and unset the immutable attribute before enrolling certificates.

--export

Export the keys we intend to enroll as EFI Signature Lists (esl), or EFI Authenticated Variables (auth) into the current working directory. Valid values are: esl, auth.

-p, --partial

Enroll keys only for the hierarchy specified. Valid values are: db, KEK, PK.

--custom-bytes

Enroll a custom bytefile provided by its path to the efivar specified by partial.

-a, --append

Instead of replacing the currently enrolled keys, append the provided one.

--keytype

Set the keytype for all signing keys used by sbctl. This includes PK, KEK and db keys. Default: file

Valid values are: file, tpm

--pk-keytype

Set the PK key type. Default: file

Valid values are: file, tpm

--kek-keytype

Set the KEK key type. Default: file

Valid values are: file, tpm

--db-keytype

Set the db key type. Default: file

Valid values are: file, tpm

sign <FILE>...

Signs an EFI binary with the created key. The file will be checked for valid signatures to avoid duplicates. -o PATH, --output PATH

Output filename. Default replaces the file.

-s, --save

Save file to the database.

sign-all

Signs all enrolled EFI binaries. -g, --generate

Generate all bundles before signing.

import-keys

Imports existing keys into sbctl. --db-cert PATH

Path to a valid Database (db) certificate.

--db-key PATH

Path to a valid Database (db) private key.

--kek-cert PATH

Path to a valid Key Exchange Key (KEK) certificate.

--kek-key PATH

Path to a valid Key Exchange Key (KEK) private key.

--pk-cert PATH

Path to a valid Platform Key(PK) certificate.

--pk-key PATH

Path to a valid Platform Key (PK) private key.

--directory PATH

Path to a key directory. The expected file locations inside this directory are:

•PK/PK.key

•PK/PK.pem

•KEK/KEK.key

•KEK/KEK.pem

•db/db.key

•db/db.pem

--force

Overwrite the existing key directory used by sbctl.

list-files, ls-files, ls

Lists all enrolled EFI binaries.

remove-file <FILE>, rm-file <FILE>, rm <FILE>

Removes the file from the signing database.

list-enrolled-keys, ls-enrolled-keys

Lists all enrolled keys on the system.

verify [FILE...]

Looks for EFI binaries with the mime type application/x-dosexec in the ESP partition, and looks at the file database. Checks if they have been signed with the Signature Database Key. Takes an optional file argument to check specific files.

reset

Resets the Platform Key. This sets the machine out of Secure Boot mode and allows key rotation. -p, --partial

Reset keys only for the hierarchy specified. Valid values are: db, KEK, PK.

rotate-keys

Rotate the secure boot keys and replace them with newly generated keys. Saves the old keys to a directory in /var/tmp and resigns any files from the file database. --backup-dir PATH

Choose backup directory for old keys.

-p, --partial

Rotate keys only for the hierarchy specified. Valid values are: db, KEK, PK.

-k, --key-file

Key file to be appended for the specified hierarchy.

-c, --cert-file

Certificate file to be appended for the specified hierarchy.

--keytype

Set the keytype for all signing keys used by sbctl. This includes PK, KEK and db keys. Default: file

Valid values are: file, tpm

--pk-keytype

Set the PK key type. Default: file

Valid values are: file, tpm

--kek-keytype

Set the KEK key type. Default: file

Valid values are: file, tpm

--db-keytype

Set the db key type. Default: file

Valid values are: file, tpm

export-enrolled-keys

Export already enrolled keys from the system. --dir PATH

Output directory for the exported keys.

--format TYPE

Format of the exported keys. Default: der Valid values: esl, auth.

setup

Setup an sbctl installation.

```
This commands enables declarative configuration of sbctl through the
configuration file. It can also print the current configuration and the
current state of the installation.
```

--setup

Setup an sbctl install based off on the provided configuration file, or the default read configuration from /etc/sbctl/sbctl.conf. This will automatically do the create-keys and enroll-keys commands and also setup the files database for signing.

See sbctl.conf(5) for details.

--migrate

Migrate the configuration and setup of sbctl to a new iteration. Currently the only migration for sbctl is moving from /usr/share/secureboot to /var/lib/sbctl.

--print-config

Prints a serialized version of the current configuration of sbctl. See sbctl.conf(5) for details.

--print-state

Prints the state of the sbctl installation. Currently only prints whether or not sbctl has been installed on the system. Note: This option requires passing --json.

help

Displays a help message.

## EFI BINARY COMMANDS
bundle [FLAGS] <NAME>

Creates a bundle that should produce EFI binaries. See BUNDLES below for more details. -a PATH, --amducode PATH

AMD microcode location.

-c PATH, --cmdline PATH

Cmdline location. (default "/etc/kernel/cmdline")

-e PATH, --efi-stub PATH

EFI Stub location. (default "/usr/lib/systemd/boot/efi/linuxx64.efi.stub")

-p PATH, --esp PATH

ESP location. (default "/efi")

-h, --help

Help for bundle.

-f PATH, --initramfs PATH

Initramfs location. (default "/boot/initramfs-linux.img")

-i PATH, --intelucode PATH

Intel microcode location.

-k PATH, --kernel-img PATH

Kernel image location. (default "/boot/vmlinuz-linux")

-o PATH, --os-release PATH

OS Release file location. (default "/usr/lib/os-release")

-s, --save

Save bundle to the database.

-l PATH, --splash-img PATH

Boot splash image location.

generate-bundles

This command generates all bundles. -s, --sign

Sign all the generated bundles.

remove-bundle <NAME>, rm-bundle <NAME>

Removes a bundle from the list. This does not delete the bundle itself.

list-bundles, ls-bundle

List all registered bundles to generate.

## OPTIONS
-j, --json

This enables supported commands to output their values in json instead of human-readable text. This is practical for parsing data with tools like jq.

-c, --config

An optionally provided path to the configuration file that should be used by sbctl. Default: /etc/sbctl/sbctl.conf

--disable-landlock

Disables landlock sandboxing in sbctl. See landlock(7).

--debug

Enable verbose debug logging. This will break the pretty printed text.

## BUNDLES
Note: This is being deprecated. Please move to dracut/mkinitcpio/ukify.

Normally, only the kernel is signed with your secure boot keys. This means the kernel command line and initramfs can be changed without possibility of verification.

Bundles are EFI executables which pack all three (initramfs, kernel and cmdline) into a single file which is easy to sign. Avoiding any unsigned files during boot makes the whole process more tamper-proof.

When a bundle is generated, its configuration is stored into the bundle database (see FILES). Subsequent executions of sbctl generate-bundles will rebuild these bundles, so you don’t need to re-specify all parameters after each system update.

Tip: systemd-boot will automatically show entries for any bundles found in esp/EFI/Linux/*.efi.

## SUPPORTED KEY TYPES
sbctl currently supports storing keys as plain unencrypted files, or as TPM shielded keys.

Plain unencrypted files (file) should only be used when the root partition is encrypted. This is the default key type for historic reasons. File keys are hardcoded to RSA 4096.

TPM shielded keys (tpm) are shielded inside the TPM and available if there is an accessible TPM on the system. TPM policies are not supported which means we can’t seal keys towards the system state. Note that TPM keys are hardcoded to RSA 2048, which is usually the highest bit strength supported by TPMs.

When creating a key hierarchy for Secure Boot, the user can decide which key type each of the keys in the hierarchy gets. Because TPMs can be slow to sign, it’s generally adviced to keep PK and KEK in the TPM, while the db key can be a standard file key.

Note that password protection is currently not supported.

## LANDLOCK
sbctl supports landlock and will attempt to restrict access to filepaths to where it’s needed during execution. Any attempts at establishing network access is also restricted.

This feature can be disabled by setting landlock: false in the configuration file, or by passing --disable-landlock to sbctl.

## OPTION ROM
See https://github.com/Foxboron/sbctl/wiki/FAQ#option-rom

## USAGE
Note: To use custom Secure Boot keys it’s important to reboot into firmware setup (systemctl reboot --firmware-setup) and navigate into the Secure Boot menu to enter Setup Mode. This is normally achieved by deleting/clearing the secure boot keys (or at a minimum the Platform Key) while leaving secure boot mode enabled. Some firmwares have a Custom Mode which only disables signature verification and should therefore not be enabled unless no other way to enter key management is provided. If this step is not completed, enrolling custom keys will be rejected by the firmware.

Next is creating the keys for secure boot. create-keys creates the key hierarchy needed for secure boot into "/var/lib/sbctl/keys".

```
# sbctl create-keys
Created Owner UUID a9fbbdb7-a05f-48d5-b63a-08c5df45ee70
Creating secure boot keys...✔
Secure boot keys created!
```

Next up is enrolling the keys into the efi firmware. sbctl supports doing this on a live system instead of having to boot or run a key management tool from the UEFI shell.

Note: This can fail because of firmware issues and unique options in the machine BIOS menu. Also, some devices have hardware firmware that is signed and validated when Secure Boot is enabled. Failing to validate this firmware could brick devices. It’s recommended to enroll your own keys with Microsoft certificates using the -m option. See Option ROM* above.

```
# sbctl enroll-keys
Enrolling keys to EFI variables...✔
Enrolled keys to the EFI variables!
```

After we have successfully enrolled the keys, we need to sign our current boot chain. Traditionally on UEFI systems one can have an EFI System Partition (ESP) on /efi, /boot or /boot/efi. One can usually find the correct one by looking at mount points or finding the EFI directory on the ESP.

The most important file to sign is the kernel. This location differs between distributions but can usually be found on the ESP or /boot. We use --save to store the file path, so we don’t need to manually sign it later.

Note that sbctl can only keep track of file paths. On versioned kernels this might prove tricky.

```
# sbctl sign --save /efi/vmlinuz-linux
✔ Signed /efi/vmlinuz-linux
```

Next is to sign the bootloader. This can usually be found on the standard path below, but might differ between installations.

```
# sbctl sign --save /efi/EFI/BOOT/BOOTX64.EFI
✔ Signed /efi/EFI/BOOT/BOOTX64.EFI
```

sbctl is able to find and verify the ESP, along with any saved files to verify we have signed the files we need.

```
# sbctl verify
Verifying file database and EFI images in /efi...
✔ /efi/EFI/BOOT/BOOTX64.EFI is signed
✔ /efi/vmlinuz-linux is signed
```

Once we have confirmed everything works, we can reboot. Once we have logged back in, we can verify the state of the system. There should be no need to re-enable Secure Boot or enter User Mode in the firmware.

```
$ sbctl status
Installed:  ✓ sbctl is installed
Owner GUID: a7b893cc-949d-408c-b5cc-6e7d0370fdb6
Setup Mode: ✓ Disabled
Secure Boot:    ✓ Enabled
```

When we do a system update, we can run sign-all to resign all the saved files from earlier.

```
# sbctl sign-all
File has already been signed /boot/vmlinuz-linux
✓ Signed /efi/EFI/BOOT/BOOTX64.EFI
```

sbctl supports creating unified kernel images. These UEFI executables bundles the initramfs, kernel and cmdline into one executable which can be signed for secure boot. This allows you to authenticate larger parts of the bootchain instead of only signing the kernel.

```
# sbctl bundle -i /boot/intel-ucode.img

               -l /usr/share/systemd/bootctl/splash-arch.bmp

               -k /boot/vmlinuz-linux

               -f /boot/initramfs-linux-lts.img

               -c /etc/kernel/cmdline

               /efi/EFI/Linux/linux-linux.efi
```

Note that dracut(8) and mkinitcpio(8) supports unified kernel features, and they should be preferred over the sbctl implementation. It is mostly provided in the cases where this feature is not supported by the initramfs generator of the distribution.

## NOTES
All commands that take path arguments convert them into absolute paths when saving them to the database.

## EXIT STATUS
On success, 0 is returned, a non-zero failure code otherwise.

## ENVIRONMENT VARIABLES
SYSTEMD_ESP_PATH, ESP_PATH

Defines the EFI system partition (ESP) location. This overrides the behaviour from sbctl where we query for the correct partition with lsblk. No checks are performed on this path and can be usefull for testing purposes.

SBCTL_UNICODE

If this value is "0" sbctl will replace the unicode symbols to equivalent ascii ones. The default value is assumed to be 1.

## FILES
/etc/sbctl/sbctl.conf:; Default configuration file. See sbctl.conf(5)

/var/lib/sbctl

Default storage directory.

/var/lib/sbctl/GUID

Owner identification. This is a randomly generated UUID.

/var/lib/sbctl/files.db

Contains a list of EFI binaries to be signed by the generated key.

/var/lib/sbctl/bundles.db

Contains a list of EFI bundles to be generated.

/var/lib/sbctl/keys/db/db.{pem,key}

Contains the Signature Database key used for signing EFI binaries.

/var/lib/sbctl/keys/KEK/KEK.{pem,key}

Contains the Key Exchange Key.

/var/lib/sbctl/keys/PK/PK.{pem,key}

Contains the Platform Key.

/var/lib/sbctl/keys/custom/KEK/*

Contains custom certificates which will be added to the firmware as additional Key Exchange Keys.

/var/lib/sbctl/keys/custom/db/*

Contains custom certificates which will be added to the firmware Signature Database.

## SEE ALSO
bootctl(1) jq(1) sbctl.conf(5) landlock(7)

## AUTHORS
•Morten Linderud <morten@linderud.pw>


sbd

package: sbd

title: sbd(8)

summary: STONITH Block Device daemon

text:
# sbd(8)

## NAME
sbd - STONITH Block Device daemon

## SYNOPSIS
sbd <-d /dev/...> [options] "command"

## SUMMARY
SBD provides a node fencing mechanism (Shoot the other node in the head, STONITH) for Pacemaker-based clusters through the exchange of messages via shared block storage such as for example a SAN, iSCSI, FCoE. This isolates the fencing mechanism from changes in firmware version or dependencies on specific firmware controllers, and it can be used as a STONITH mechanism in all configurations that have reliable shared storage.

SBD can also be used without any shared storage. In this mode, the watchdog device will be used to reset the node if it loses quorum, if any monitored daemon is lost and not recovered or if Pacemaker decides that the node requires fencing.

The sbd binary implements both the daemon that watches the message slots as well as the management tool for interacting with the block storage device(s). This mode of operation is specified via the "command" parameter; some of these modes take additional parameters.

To use SBD with shared storage, you must first "create" the messaging layout on one to three block devices. Second, configure /etc/sysconfig/sbd to list those devices (and possibly adjust other options), and restart the cluster stack on each node to ensure that "sbd" is started. Third, configure the "external/sbd" fencing resource in the Pacemaker CIB.

Each of these steps is documented in more detail below the description of the command options.

"sbd" can only be used as root.

### GENERAL OPTIONS
-d /dev/...

Specify the block device(s) to be used. If you have more than one, specify this option up to three times. This parameter is mandatory for all modes, since SBD always needs a block device to interact with. This man page uses /dev/sda1, /dev/sdb1, and /dev/sdc1 as example device names for brevity. However, in your production environment, you should instead always refer to them by using the long, stable device name (e.g., /dev/disk/by-id/dm-uuid-part1-mpath-3600508b400105b5a0001500000250000).

-v|-vv|-vvv

Enable verbose|debug|debug-library logging (optional)

-h

Display a concise summary of "sbd" options.

-n node

Set local node name; defaults to "uname -n". This should not need to be set.

-R

Do not enable realtime priority. By default, "sbd" runs at realtime priority, locks itself into memory, and also acquires highest IO priority to protect itself against interference from other processes on the system. This is a debugging-only option.

-I N

Async IO timeout (defaults to 3 seconds, optional). You should not need to adjust this unless your IO setup is really very slow. (In daemon mode, the watchdog is refreshed when the majority of devices could be read within this time.)

### create
Example usage:

```
        sbd -d /dev/sdc2 -d /dev/sdd3 create
```

If you specify the create command, sbd will write a metadata header to the device(s) specified and also initialize the messaging slots for up to 255 nodes.

Warning: This command will not prompt for confirmation. Roughly the first megabyte of the specified block device(s) will be overwritten immediately and without backup.

This command accepts a few options to adjust the default timings that are written to the metadata (to ensure they are identical across all nodes accessing the device).

-1 N

Set watchdog timeout to N seconds. This depends mostly on your storage latency; the majority of devices must be successfully read within this time, or else the node will self-fence. If your sbd device(s) reside on a multipath setup or iSCSI, this should be the time required to detect a path failure. You may be able to reduce this if your device outages are independent, or if you are using the Pacemaker integration.

-2 N

Set slot allocation timeout to N seconds. You should not need to tune this.

-3 N

Set daemon loop timeout to N seconds. You should not need to tune this.

-4 N

Set msgwait timeout to N seconds. This should be twice the watchdog timeout. This is the time after which a message written to a node's slot will be considered delivered. (Or long enough for the node to detect that it needed to self-fence.) This also affects the stonith-timeout in Pacemaker's CIB; see below.

### list
Example usage:

```
        # sbd -d /dev/sda1 list
        0       hex-0   clear
        1       hex-7   clear
        2       hex-9   clear
```

List all allocated slots on device, and messages. You should see all cluster nodes that have ever been started against this device. Nodes that are currently running should have a clear state; nodes that have been fenced, but not yet restarted, will show the appropriate fencing message.

### dump
Example usage:

```
        # sbd -d /dev/sda1 dump
        ==Dumping header on disk /dev/sda1
        Header version     : 2
        Number of slots    : 255
        Sector size        : 512
        Timeout (watchdog) : 15
        Timeout (allocate) : 2
        Timeout (loop)     : 1
        Timeout (msgwait)  : 30
        ==Header on disk /dev/sda1 is dumped
```

Dump meta-data header from device.

### watch
Example usage:

```
        sbd -d /dev/sdc2 -d /dev/sdd3 -P watch
```

This command will make "sbd" start in daemon mode. It will constantly monitor the message slot of the local node for incoming messages, reachability, and optionally take Pacemaker's state into account.

"sbd" must be started on boot before the cluster stack! See below for enabling this according to your boot environment.

The options for this mode are rarely specified directly on the commandline directly, but most frequently set via /etc/sysconfig/sbd.

It also constantly monitors connectivity to the storage device, and self-fences in case the partition becomes unreachable, guaranteeing that it does not disconnect from fencing messages.

A node slot is automatically allocated on the device(s) the first time the daemon starts watching the device; hence, manual allocation is not usually required.

If a watchdog is used together with the "sbd" as is strongly recommended, the watchdog is activated at initial start of the sbd daemon. The watchdog is refreshed every time the majority of SBD devices has been successfully read. Using a watchdog provides additional protection against "sbd" crashing.

If the Pacemaker integration is activated, "sbd" will not self-fence if device majority is lost, if:

1.

The partition the node is in is still quorate according to the CIB;

2.

it is still quorate according to Corosync's node count;

3.

the node itself is considered online and healthy by Pacemaker.

This allows "sbd" to survive temporary outages of the majority of devices. However, while the cluster is in such a degraded state, it can neither successfully fence nor be shutdown cleanly (as taking the cluster below the quorum threshold will immediately cause all remaining nodes to self-fence). In short, it will not tolerate any further faults. Please repair the system before continuing.

There is one "sbd" process that acts as a master to which all watchers report; one per device to monitor the node's slot; and, optionally, one that handles the Pacemaker integration.

-W

Enable or disable use of the system watchdog to protect against the sbd processes failing and the node being left in an undefined state. Specify this once to enable, twice to disable. Defaults to enabled.

-w /dev/watchdog

This can be used to override the default watchdog device used and should not usually be necessary.

-p /run/sbd.pid

This option can be used to specify a pidfile for the main sbd process.

-F N

Number of failures before a failing servant process will not be restarted immediately until the dampening delay has expired. If set to zero, servants will be restarted immediately and indefinitely. If set to one, a failed servant will be restarted once every -t seconds. If set to a different value, the servant will be restarted that many times within the dampening period and then delay. Defaults to 1.

-t N

Dampening delay before faulty servants are restarted. Combined with "-F 1", the most logical way to tune the restart frequency of servant processes. Default is 5 seconds. If set to zero, processes will be restarted indefinitely and immediately.

-P

Enable Pacemaker integration which checks Pacemaker quorum and node health. Specify this once to enable, twice to disable. Defaults to enabled.

-S N

Set the start mode. (Defaults to 0.) If this is set to zero, sbd will always start up unconditionally, regardless of whether the node was previously fenced or not.

If set to one, sbd will only start if the node was previously shutdown cleanly (as indicated by an exit request message in the slot), or if the slot is empty. A reset, crashdump, or power-off request in any slot will halt the start up.

This is useful to prevent nodes from rejoining if they were faulty. The node must be manually "unfenced" by sending an empty message to it:

```
        sbd -d /dev/sda1 message node1 clear

```

-s N

Set the start-up wait time for devices. (Defaults to 120.) Dynamic block devices such as iSCSI might not be fully initialized and present yet. This allows one to set a timeout for waiting for devices to appear on start-up. If set to 0, start-up will be aborted immediately if no devices are available.

-Z

Enable trace mode. Warning: this is unsafe for production, use at your own risk! Specifying this once will turn all reboots or power-offs, be they caused by self-fence decisions or messages, into a crashdump. Specifying this twice will just log them but not continue running.

-T

By default, the daemon will set the watchdog timeout as specified in the device metadata. However, this does not work for every watchdog device. In this case, you must manually ensure that the watchdog timeout used by the system correctly matches the SBD settings, and then specify this option to allow "sbd" to continue with start-up.

-5 N

Warn if the time interval for tickling the watchdog exceeds this many seconds. Since the node is unable to log the watchdog expiry (it reboots immediately without a chance to write its logs to disk), this is very useful for getting an indication that the watchdog timeout is too short for the IO load of the system. Default is about 3/5 of watchdog timeout, set to zero to disable.

-C N

Watchdog timeout to set before crashdumping. If SBD is set to crashdump instead of reboot - either via the trace mode settings or the external/sbd fencing agent's parameter -, SBD will adjust the watchdog timeout to this setting before triggering the dump. Otherwise, the watchdog might trigger and prevent a successful crashdump from ever being written. Set to zero (= default) to disable.

-r N

Actions to be executed when the watchers don't timely report to the sbd master process or one of the watchers detects that the master process has died. Set timeout-action to comma-separated combination of noflush|flush plus reboot|crashdump|off. If just one of both is given the other stays at the default.

This doesn't affect actions like off, crashdump, reboot explicitly triggered via message slots. And it does as well not configure the action a watchdog would trigger should it run off (there is no generic interface).

Defaults to flush,reboot.

### allocate
Example usage:

```
        sbd -d /dev/sda1 allocate node1
```

Explicitly allocates a slot for the specified node name. This should rarely be necessary, as every node will automatically allocate itself a slot the first time it starts up on watch mode.

### message
Example usage:

```
        sbd -d /dev/sda1 message node1 test
```

Writes the specified message to node's slot. This is rarely done directly, but rather abstracted via the "external/sbd" fencing agent configured as a cluster resource.

Supported message types are:

test

This only generates a log message on the receiving node and can be used to check if SBD is seeing the device. Note that this could overwrite a fencing request send by the cluster, so should not be used during production.

reset

Reset the target upon receipt of this message.

off

Power-off the target.

crashdump

Cause the target node to crashdump.

exit

This will make the "sbd" daemon exit cleanly on the target. You should not send this message manually; this is handled properly during shutdown of the cluster stack. Manually stopping the daemon means the node is unprotected!

clear

This message indicates that no real message has been sent to the node. You should not set this manually; "sbd" will clear the message slot automatically during start-up, and setting this manually could overwrite a fencing message by the cluster.

### query-watchdog
Example usage:

```
        sbd query-watchdog
```

Check for available watchdog devices and print some info.

Warning: This command will arm the watchdog during query, and if your watchdog refuses disarming (for example, if its kernel module has the 'nowayout' parameter set) this will reset your system.

### test-watchdog
Example usage:

```
        sbd test-watchdog [-w /dev/watchdog3]
```

Test specified watchdog device (/dev/watchdog by default).

Warning: This command will arm the watchdog and have your system reset in case your watchdog is working properly! If issued from an interactive session, it will prompt for confirmation.

## Base system configuration

### Configure a watchdog
It is highly recommended that you configure your Linux system to load a watchdog driver with hardware assistance (as is available on most modern systems), such as hpwdt, iTCO_wdt, or others. As a fall-back, you can use the softdog module.

No other software must access the watchdog timer; it can only be accessed by one process at any given time. Some hardware vendors ship systems management software that use the watchdog for system resets (f.e. HP ASR daemon). Such software has to be disabled if the watchdog is to be used by SBD.

### Choosing and initializing the block device(s)
First, you have to decide if you want to use one, two, or three devices.

If you are using multiple ones, they should reside on independent storage setups. Putting all three of them on the same logical unit for example would not provide any additional redundancy.

The SBD device can be connected via Fibre Channel, Fibre Channel over Ethernet, or even iSCSI. Thus, an iSCSI target can become a sort-of network-based quorum server; the advantage is that it does not require a smart host at your third location, just block storage.

The SBD partitions themselves must not be mirrored (via MD, DRBD, or the storage layer itself), since this could result in a split-mirror scenario. Nor can they reside on cLVM2 volume groups, since they must be accessed by the cluster stack before it has started the cLVM2 daemons; hence, these should be either raw partitions or logical units on (multipath) storage.

The block device(s) must be accessible from all nodes. (While it is not necessary that they share the same path name on all nodes, this is considered a very good idea.)

SBD will only use about one megabyte per device, so you can easily create a small partition, or very small logical units. (The size of the SBD device depends on the block size of the underlying device. Thus, 1MB is fine on plain SCSI devices and SAN storage with 512 byte blocks. On the IBM s390x architecture in particular, disks default to 4k blocks, and thus require roughly 4MB.)

The number of devices will affect the operation of SBD as follows:

One device

In its most simple implementation, you use one device only. This is appropriate for clusters where all your data is on the same shared storage (with internal redundancy) anyway; the SBD device does not introduce an additional single point of failure then. If the SBD device is not accessible, the daemon will fail to start and inhibit startup of cluster services.

Two devices

This configuration is a trade-off, primarily aimed at environments where host-based mirroring is used, but no third storage device is available. SBD will not commit suicide if it loses access to one mirror leg; this allows the cluster to continue to function even in the face of one outage.

However, SBD will not fence the other side while only one mirror leg is available, since it does not have enough knowledge to detect an asymmetric split of the storage. So it will not be able to automatically tolerate a second failure while one of the storage arrays is down. (Though you can use the appropriate crm command to acknowledge the fence manually.)

It will not start unless both devices are accessible on boot.

Three devices

In this most reliable and recommended configuration, SBD will only self-fence if more than one device is lost; hence, this configuration is resilient against temporary single device outages (be it due to failures or maintenance). Fencing messages can still be successfully relayed if at least two devices remain accessible. This configuration is appropriate for more complex scenarios where storage is not confined to a single array. For example, host-based mirroring solutions could have one SBD per mirror leg (not mirrored itself), and an additional tie-breaker on iSCSI.

It will only start if at least two devices are accessible on boot.

After you have chosen the devices and created the appropriate partitions and perhaps multipath alias names to ease management, use the "sbd create" command described above to initialize the SBD metadata on them.

Sharing the block device(s) between multiple clusters

It is possible to share the block devices between multiple clusters, provided the total number of nodes accessing them does not exceed 255 nodes, and they all must share the same SBD timeouts (since these are part of the metadata).

If you are using multiple devices this can reduce the setup overhead required. However, you should not share devices between clusters in different security domains.

### Configure SBD to start on boot
On systems using "sysvinit", the "openais" or "corosync" system start-up scripts must handle starting or stopping "sbd" as required before starting the rest of the cluster stack.

For "systemd", sbd simply has to be enabled using

```
        systemctl enable sbd.service
```

The daemon is brought online on each node before corosync and Pacemaker are started, and terminated only after all other cluster components have been shut down - ensuring that cluster resources are never activated without SBD supervision.

### Configuration via sysconfig
The system instance of "sbd" is configured via /etc/sysconfig/sbd. In this file, you must specify the device(s) used, as well as any options to pass to the daemon:

```
        SBD_DEVICE="/dev/sda1;/dev/sdb1;/dev/sdc1"
        SBD_PACEMAKER="true"
```

"sbd" will fail to start if no "SBD_DEVICE" is specified. See the installed template or section for configuration via environment for more options that can be configured here. In general configuration done via parameters takes precedence over the configuration from the configuration file.

### Configuration via environment
SBD_DEVICE

Allows "string" defaulting to "" SBD_DEVICE specifies the devices to use for exchanging sbd messages and to monitor. If specifying more than one path, use ";" as separator.

SBD_PACEMAKER

Allows "yesno" defaulting to "yes" Whether to enable the pacemaker integration.

SBD_STARTMODE

Allows "always / clean" defaulting to "always" Specify the start mode for sbd. Setting this to "clean" will only allow sbd to start if it was not previously fenced. See the -S option in the man page.

SBD_DELAY_START

Allows "yesno / integer" defaulting to "no" Whether to delay after starting sbd on boot for "msgwait" seconds. This may be necessary if your cluster nodes reboot so fast that the other nodes are still waiting in the fence acknowledgement phase. This is an occasional issue with virtual machines.

This can also be enabled by being set to a specific delay value, in seconds. Sometimes a longer delay than the default, "msgwait", is needed, for example in the cases where it's considered to be safer to wait longer than: corosync token timeout + consensus timeout + pcmk_delay_max + msgwait

Be aware that the special value "1" means "yes" rather than "1s".

Consider that you might have to adapt the startup-timeout accordingly if the default isn't sufficient. (TimeoutStartSec for systemd)

This option may be ignored at a later point, once pacemaker handles this case better.

SBD_WATCHDOG_DEV

Allows "string" defaulting to "/dev/watchdog" Watchdog device to use. If set to /dev/null, no watchdog device will be used.

SBD_WATCHDOG_TIMEOUT

Allows "integer" defaulting to 5 How long, in seconds, the watchdog will wait before panicking the node if no-one tickles it.

This depends mostly on your storage latency; the majority of devices must be successfully read within this time, or else the node will self-fence.

If your sbd device(s) reside on a multipath setup or iSCSI, this should be the time required to detect a path failure.

Be aware that watchdog timeout set in the on-disk metadata takes precedence.

SBD_TIMEOUT_ACTION

Allows "string" defaulting to "flush,reboot" Actions to be executed when the watchers don't timely report to the sbd master process or one of the watchers detects that the master process has died.

Set timeout-action to comma-separated combination of noflush|flush plus reboot|crashdump|off. If just one of both is given the other stays at the default.

This doesn't affect actions like off, crashdump, reboot explicitly triggered via message slots. And it does as well not configure the action a watchdog would trigger should it run off (there is no generic interface).

SBD_MOVE_TO_ROOT_CGROUP

Allows "yesno / auto" defaulting to "auto" If CPUAccounting is enabled default is not to assign any RT-budget to the system.slice which prevents sbd from running RR-scheduled.

One way to escape that issue is to move sbd-processes from the slice they were originally started to root-slice. Of course starting sbd in a certain slice might be intentional. Thus in auto-mode sbd will check if the slice has RT-budget assigned. If that is the case sbd will stay in that slice while it will be moved to root-slice otherwise.

SBD_SYNC_RESOURCE_STARTUP

Allows "yesno" defaulting to "yes" If resource startup syncing is enabled then pacemakerd is gonna wait to be pinged via IPC before it starts resources. On shutdown pacemakerd is going to wait in a state where it has cleanly shutdown resources till sbd fetches that state.

The default is set when building SBD and Pacemaker from source. Going for 'no' is safer if it can't be assured that SBD and Pacemaker installed do both support the synchronization feature. When going with 'yes' - also using package dependencies to assure SBD & Pacemaker both support the synchronization feature and are assuming the same default - an SBD configuration inherited via an upgrade doesn't have to be altered to still benefit from the new feature.

SBD_OPTS

Allows "string" defaulting to "" Additional options for starting sbd

### Testing the sbd installation
After a restart of the cluster stack on this node, you can now try sending a test message to it as root, from this or any other node:

```
        sbd -d /dev/sda1 message node1 test
```

The node will acknowledge the receipt of the message in the system logs:

```
        Aug 29 14:10:00 node1 sbd: [13412]: info: Received command test from node2
```

This confirms that SBD is indeed up and running on the node, and that it is ready to receive messages.

Make sure that /etc/sysconfig/sbd is identical on all cluster nodes, and that all cluster nodes are running the daemon.

## Pacemaker CIB integration

### Fencing resource
Pacemaker can only interact with SBD to issue a node fence if there is a configure fencing resource. This should be a primitive, not a clone, as follows:

```
        primitive fencing-sbd stonith:external/sbd \
                params pcmk_delay_max=30
```

This will automatically use the same devices as configured in /etc/sysconfig/sbd.

While you should not configure this as a clone (as Pacemaker will register the fencing device on each node automatically), the pcmk_delay_max setting enables random fencing delay which ensures, in a scenario where a split-brain scenario did occur in a two node cluster, that one of the nodes has a better chance to survive to avoid double fencing.

SBD also supports turning the reset request into a crash request, which may be helpful for debugging if you have kernel crashdumping configured; then, every fence request will cause the node to dump core. You can enable this via the "crashdump="true"" parameter on the fencing resource. This is not recommended for production use, but only for debugging phases.

### General cluster properties
You must also enable STONITH in general, and set the STONITH timeout to be at least twice the msgwait timeout you have configured, to allow enough time for the fencing message to be delivered. If your msgwait timeout is 60 seconds, this is a possible configuration:

```
        property stonith-enabled="true"
        property stonith-timeout="120s"
```

Caution: if stonith-timeout is too low for msgwait and the system overhead, sbd will never be able to successfully complete a fence request. This will create a fencing loop.

Note that the sbd fencing agent will try to detect this and automatically extend the stonith-timeout setting to a reasonable value, on the assumption that sbd modifying your configuration is preferable to not fencing.

## Management tasks

### Recovering from temporary SBD device outage
If you have multiple devices, failure of a single device is not immediately fatal. "sbd" will retry to restart the monitor for the device every 5 seconds by default. However, you can tune this via the options to the watch command.

In case you wish the immediately force a restart of all currently disabled monitor processes, you can send a SIGUSR1 to the SBD inquisitor process.

## LICENSE
Copyright (C) 2008-2013 Lars Marowsky-Bree

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

For details see the GNU General Public License at http://www.gnu.org/licenses/gpl-2.0.html (version 2) and/or http://www.gnu.org/licenses/gpl.html (the newest as per "any later").


scanlogd

package: scanlogd

title: scanlogd(8)

summary: detects and logs TCP port scans

text:
# scanlogd(8)

## NAME
scanlogd - detects and logs TCP port scans

## SYNOPSIS
scanlogd

## DESCRIPTION
scanlogd detects port scans and writes one line per scan via the syslog(3) mechanism. If a source address sends multiple packets to different ports in a short time, the event will be logged. The format of the messages is:

saddr[:sport] to daddr [and others,] ports port[, port...], ..., flags[, TOS TOS][, TTL TTL] @HH:MM:SS

The fields in square brackets are optional; sport, TOS, and TTL will only be displayed if they were constant during the scan.

The flags field represents TCP control bits seen in packets coming to the system from the address of the scan. It is a combination of eight characters, with each corresponding to one of the six defined and two reserved TCP control bits (see RFC 793). Control bits that were always set are encoded with an uppercase letter, and a lowercase letter is used if the bit was always clear. A question mark is used to indicate bits that changed from packet to packet.

## INTERFACES
In order to do its job, scanlogd needs a way to obtain raw IP packets that either come to the system scanlogd is running on, or travel across a network segment that is directly connected to the system. Current versions of scanlogd can be built with support for one of several packet capture interfaces.

scanlogd is aware of the raw socket interface on Linux, libnids, and libpcap.

The use of libpcap alone is discouraged. If you're on a system other than Linux and/or want to monitor the traffic of an entire network at once, you should be using libnids in order to handle fragmented IP packets.

## COMPILE-TIME DEFAULTS
At least 7 different privileged or 21 non-privileged ports, or a weighted combination of those, have to be accessed with no longer than 3 seconds between the accesses to be treated as a scan. If more than 5 scans are detected within 20 seconds, that event will be logged and logging will be stopped temporarily.

Logging is done with a facility of daemon and a priority level alert.

scanlogd should be started as root since it needs access to a packet capture interface. By default, it chroots to /var/empty and switches to running as user scanlogd after the packet capture interface is initialized.

## EXIT STATUS
If the daemon couldn't start up successfully, it will exit with a status of 1.

## USAGE
You're expected to create a dummy user for scanlogd to run as. Make sure you allocate unique UID and GID to the user.

In most cases, scanlogd should be started from a rc.d script on system startup.

In /etc/syslog.conf you may use something like:

daemon.alert /var/log/alert

## SECURITY NOTES
As the name indicates, scanlogd only logs port scans. It does not prevent them. You will only receive summarized information in the system's log.

Obviously, the source address of port scans can be spoofed. Don't take any action against the source of attacks unless other evidence is available. Sometimes IP addresses are shared between many people; this is the case for ISP shell servers, dynamic dialup pools, and corporate networks behind NAT (masquerading).

## BUGS
Due to the nature of port scans, both false positives (detecting a scan when there isn't one) and false negatives (not detecting a scan when there's one) are possible. In particular, false positives occur when many small files are transferred rapidly with passive mode FTP.

## AUTHORS

```
Solar Designer <solar at openwall.com>
```

Steffen Dettmer <steffen at dett.de> wrote the initial version of this manual page.

## SEE ALSO
syslog(3), syslog.conf(5), libnids(3), pcap(3)

```
scanlogd home page: http://www.openwall.com/scanlogd/
Phrack Magazine, issue 53, article 13
```


schedtool

package: schedtool

title: schedtool(8)

summary: query and set CPU scheduling parameters

text:
# schedtool(8)

## NAME
schedtool - query and set CPU scheduling parameters

## SYNOPSIS
schedtool

```
[-0|-N] [-1|-F] [-2|-R] [-3|-B] [-4|-I] [-5|-D]
[-M policy]
[-a affinity]
[-p prio]
[-n nice_level]
[-e command [arg ...]]
[-r]
[-v]
[-h]
[LIST OF PIDs]
```

## DESCRIPTION
schedtool can set all CPU scheduling parameters Linux is capable of or display information for given processes.

Long-running, non-interactive tasks may benefit from SCHED_BATCH as timeslices are longer, less system-time is wasted by computing the next runnable process and the caches stay stable.

Audio/video or other near-realtime applications may run with less skipping if set to SCHED_RR. Use the static priority-switch -p to designate inter-process-hierarchies.

schedtool now supports setting the CPU-affinity introduced in linux 2.5.8.

## OPTIONS
-N or -0

set all PIDs to SCHED_NORMAL/OTHER

-F or -1

to SCHED_FIFO root-credentials required

-R or -2

to SCHED_RR root-credentials required

-B or -3

to SCHED_BATCH

-I or -4

to SCHED_ISO

-D or -5

to SCHED_IDLEPRIO

-M policy

for manual/raw mode; policy is the number of the scheduling policy (see above for 0-4). This option is mostly for kernel guys that want to test their new implementations.

-p prio

specify static priority required for SCHED_FIFO and SCHED_RR. Usually ranged from 1-99.

-a affinity

set the PID's affinity to this bitmask (hexadecimal); alternatively, a list mode is supported.

-n nice_level

set the PID's nice level; see nice(2), nice(1).

-e command [arg ...]

execute command with given scheduling parameters (overwrites schedtool's process image). See EXAMPLES.

-r

display min and max priority for each policy.

-v

be verbose.

-h

help

## EXAMPLES
To query the $SHELL's policies:

```
    #> schedtool $$
To query some PIDs, namely 1 2 and 3:
```

```
    #> schedtool 1 2 3
```

To execute mplayer in SCHED_RR with priority 20. The priority arg is needed for both SCHED_RR and SCHED_FIFO.

```
    #> schedtool -R -p 20 -e mplayer -quiet some_file.avi
```

To set current shell to SCHED_BATCH, which all programs the shell starts will inherit:

```
    #> schedtool -3 $$
```

To set all processes with the name 'cpu_hog' to SCHED_BATCH:

```
    #> schedtool -3 `pidof cpu_hog`
```

To set a process' affinity to only the first CPU (CPU0):

```
    #> schedtool -a 0x1 <PID>
Using the list mode and affinty of CPU0 and CPU3:
```

```
    #> schedtool -a 0,3 <PID>
```

A combination of an affinity and a policy-argument is - of course - always possible.

```
   #> schedtool -B -a 0x1 <PID>
```

## AFFINITY MASK
The affinity-argument determines on which CPUs a process is allowed to run. It consists of a simple bitmask represented in hexadecimal. CPU0 is denoted by the least-significant bit, CPU1 by the second least-significant and so on, thus giving:

0x1 -> only run on CPU0

0x2 -> only run on CPU1

0x4 -> only run on CPU2

0x8 -> only run on CPU3 ... and so on.

Multi-target CPUs may be specified using bitwise OR of the values:

0x7 -> run on CPUs 0, 1, 2 but NOT on 4

0x3 -> run only on CPUs 0 and 1

The default is to run a process on all CPUs, giving a mask of

0xf for all 4 CPUs

0xff for all 8 CPUs

## AFFINITY MASK - LIST MODE
Alternatively a list mode is supported where you can specify the CPUs delimited by ",". The following runs <PID> on CPU0 and CPU1 (equivalent to 0x3):

```
   #> schedtool -a 0,1 <PID>
```

## POLICY OVERVIEW
SCHED_NORMAL / SCHED_OTHER This is the default policy and for the average program with some interaction. Does preemption of other processes.

SCHED_FIFO First-In, First Out Scheduler, used only for real-time contraints. Processes in this class are usually not preempted by others, they need to free themselves from the CPU via sched_yield() and as such you need special designed applications. Use with extreme care. ROOT-credentials required.

SCHED_RR Round-Robin Scheduler, also used for real-time constraints. CPU-time is assigned in an round-robin fashion with a much smaller timeslice than with SCHED_NORMAL and processes in this group are favoured over SCHED_NORMAL. Usable for audio/video applications near peak rate of the system. ROOT-credentials required.

SCHED_BATCH [ since 2.6.16 in mainline ] SCHED_BATCH was designed for non-interactive, CPU-bound applications. It uses longer timeslices (to better exploit the cache), but can be interrupted anytime by other processes in other classes to guaratee interaction of the system. Processes in this class are selected last but may result in a considerable speed-up (up to 300%). No interactive boosting is done.

SCHED_ISO [ patch needed ] SCHED_ISO was designed to give users a SCHED_RR-similar class. To quote Con Kolivas: "This is a non-expiring scheduler policy designed to guarantee a timeslice within a reasonable latency while preventing starvation. Good for gaming, video at the limits of hardware, video capture etc."

SCHED_IDLEPRIO [ patch needed ] SCHED_IDLEPRIO is similar to SCHED_BATCH, but was explicitely designed to consume only the time the CPU is idle. No interactive boosting is done. If you used SCHED_BATCH in the -ck kernels this is what you want since 2.6.16

## HINTS
PID 0 means "current process", in our case, schedtool. May occur when using the -e switch.

Be careful with SCHED_FIFO! You may lock out other processes from the CPU, including your shell.

For SCHED_BATCH you certainly need the a recent 2.6 kernel.

A short overview is given in SCHED_DESIGN and the README contains thourough discussion. The INSTALL file also lists all prerequisites and where you can get patches.

Affinity 0x0 should never be used.

## SEE ALSO
sched_setscheduler(2), sched_setaffinity(2), nice(2), nice(1), renice(3).

## BUGS
You need some knowledge about the kernel and scheduling. The author is a grumpy little elitist.

## AUTHOR
Freek

Please contact me via freshmeat.net's "contact author"-feature (http://freshmeat.net/projects/schedtool).


scponly

package: scponly

title: scponly(8)

text:
# scponly(8)

## NAME
scponly

## SYNOPSIS
scponly

— limited shell for secure file transfers

## DESCRIPTION
scponly is an alternative "shell" (of sorts) for system administrators who would like to provide access to remote users to both read and write local files without providing any remote execution privileges. Functionally, it is best described as a wrapper to the trusted suite of ssh applications.

A typical usage of scponly is in creating a semi-public account not unlike the concept of anonymous login for ftp. This allows an administrator to share files in the same way an anonymous ftp setup would, only employing all the protection that ssh provides. This is especially significant if you consider that ftp authentications traverse public networks in a plaintext format.

Instead of just a single anonymous user, scponly supports configuring potentially many users, each of which could be set up to provide access to distinct directory trees. Aside from the installation details, each of these users would have their default shell in /etc/passwd set to "/usr/local/bin/scponly" (or wherever you choose to install it). This would mean users with this shell can neither login interactively or execute commands remotely. They can however, scp files in and out, governed by the usual Unixish file permissions.

## FEATURES

- Logging: scponly logs time, client IP address, username, and the actual request to syslog.

- chroot: scponly can chroot to the user's home directory (or any other directory the user has permissions for), disallowing access to the rest of the filesystem.

- sftp compatibility: My testing of sftp against an scponly user worked great. This is probably the cleanest and most usable way for an scponly user to access files.

- Security checks: root login is disallowed (though root should never be configured to be using scponly as the default shell.)

- WinSCP 2.0 compatibility: scponly can be compiled in WinSCP compatibility mode that will permit a "semi-interactive" shell that WinSCP can use.

- gftp compatibility: scponly is compatible with gftp if you set "use ssh2 sftp subsys" in your gftp options.

scponly doesn't do anything to manage read/write permissions. The ssh applications already do that just fine. If you use scponly, be aware that good old Unix-style file permissions are still doing the work of protecting your files.

## NOTES

- As recent as June 26, 2002, vulnerabilities have been discovered in OpenSSH. There is also a SSH1 protocol vulnerability. If you're going to use scponly , be aware it is no more secure than the ssh installation it runs on.

- I've since discovered that ssh.com's commercial ssh offering supports BOTH "dummy users" as well as functionality paralleling scponly. I have not been able to find any notes on these features, but I did read that they exist. I will make a point to include more information later. It appears that OpenSSH does not yet support these features. At this time, I have no plans to end-of-life scponly, though ultimately, I recognize that scponly should eventually become just a feature of whichever sshd you may run.

## FILES
/usr/local/bin/scponly

The default location for the shell itself.

/usr/local/sbin/scponlyc

The default location for the chrooted version of scponly

/etc/shells

To be a proper shell, it has to be included here.

## SEE ALSO
chroot(2), ssh(1), scp(1), sftp(1), shells(5), sshd(8).

## AUTHORS
Joe Boyle ⟨joe@sublimation.org⟩.

## LEGALITIES
Copyright (C) 2001, 2002, 2003

Joe Boyle ⟨joe@sublimation.org⟩.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

## BUGS
Versions prior to 2.4 have a vulnerability wherein the .ssh/environment file can be used to override $PATH and $LD_LIBRARY_PATH vars, compromising the shell.


scrounge-ntfs

package: scrounge-ntfs

title: scrounge-ntfs(8)

text:
# scrounge-ntfs(8)

## NAME
scrounge-ntfs — helps retrieve data from corrupted NTFS partitions

## SYNOPSIS
scrounge-ntfs

-l disk

scrounge-ntfs

-s disk

scrounge-ntfs

[-m mftoffset] [-c clustersize] [-o outdir] disk start end

## DESCRIPTION
scrounge-ntfs is a utility that can rescue data from corrupted NTFS partitions. It writes the files retrieved to another working file system. Certain information about the partition needs to be known in advance.

The -l mode is meant to be run in advance of the data corruption, with the output stored away in a file. This allows scrounge-ntfs to recover data reliably. See the 'NOTES' section below for recover info when this isn't the case.

## OPTIONS
The options are as follows:

-c

The cluster size (in sectors). When not specified a default of 8 is used.

-l

List partition information for a drive. This will only work when the partition table for the given drive is intact.

-m

When recovering data this specifies the location of the MFT from the beginning of the partition (in sectors). If not specified then no directory information can be used, that is, all rescued files will be written to the same directory.

-o

Directory to put rescued files in. If not specified then files will be placed in the current directory.

-s

Search disk for partition information. (Not implemented yet).

disk

The raw device used to access the disk which contains the NTFS partition to rescue files from. eg: '/dev/hdc'

start

The beginning of the NTFS partition (in sectors).

end

The end of the NTFS partition (in sectors)

## NOTES
If you plan on using this program sucessfully you should prepare in advance by storing a copy of the partition information. Use the -l option to do this. Eventually searching for disk partition information will be implemented, which will solve this problem.

When only one partition exists on a disk or you want to rescue the first partition there are ways to guess at the sector sizes and MFT location. See the scrounge-ntfs web page for more info:

http://memberwebs.com/swalter/software/scrounge/

## AUTHOR
Stef Walter ⟨stef@memberwebs.com⟩


scsiadd

package: scsiadd

title: scsiadd(8)

summary: Add and remove SCSI devices

text:
# scsiadd(8)

## NAME
scsiadd - Add and remove SCSI devices

## SYNOPSIS
scsiadd {-a|-r} <id>

scsiadd {-a|-r} <id> <lun>

scsiadd {-a|-r} <host> <id> <lun>

scsiadd {-a|-r} <host> <channel> <id> <lun>

scsiadd [-i maxid] -s <host>

scsiadd [-i maxid] -s <host> <channel>

scsiadd -p

## DESCRIPTION
scsiadd adds and removes devices, scans for new devices, or prints the status of the SCSI bus. The options are:

-a

add device

-r

remove device

-s

scan for new devices

-p

print SCSI status

-i

set maximum SCSI ID which is scanned

## FILES
scsiadd need the /proc/scsi/scsi file to send its commands to the linux kernel. In 2.6 kernels this file is considered deprecated and you have to enable the following kernel option so this file is generated:

Device Drivers->SCSI device support->legacy /proc/scsi/ support

## EXAMPLES
scsiadd 3

add SCSI device with ID 3 on primary host

scsiadd -r 1

remove SCSI device with ID 1 from primary host

scsiadd -s

scan for new devices on primary device

scsiadd -a 1 2 13 4

add SCSI device with ID 13 and LUN 4 on host 1 channel 2

## AUTHOR
Dirk Jagdmann <doj@cubic.org>

The latest version can be found at http://llg.cubic.org/tools

## SEE ALSO
http://www.tldp.org/HOWTO/SCSI-2.4-HOWTO/index.html

Howto describing many aspects of the Linux 2.4.0 SCSI system


tgt-admin

package: scsitarget-utils

title: tgt-admin(8)

summary: Linux SCSI Target Configuration Tool

text:
# tgt-admin(8)

## NAME
tgt-admin - Linux SCSI Target Configuration Tool

## SYNOPSIS
tgt-admin [-e --execute] [--delete <value>] [--offline <value>] [--ready <value>] [-s --show] [-C --control-port <NNNN>] [-c --conf <file>] [--ignore-errors] [-f --force] [-p --pretend] [--dump] [-v --verbose] [-h --help]

## DESCRIPTION
tgt-admin is a utility which allows a persistent configuration of targets and luns. It uses tgtadm commands to create, delete and show targets.

## OPTIONS
-e, --execute

Read /etc/tgt/targets.conf and execute tgtadm commands. If the target already exists, it won't be processed. See --update.

-d, --delete <value>

Delete all or selected targets. The target will be deleted only if it's not used (no initiator is connected to it). If you want to delete targets which are in use, you have to add the "--force" flag.

```
Example usage:

    --delete ALL            - delete all targets

    --delete tid=4          - delete target 4

                              (target with tid 4)

    --delete iqn.2008-08.com.example:some.target

                            - delete this target

```

--offline

Put all or selected targets in offline state.

```
Example usage:

    --offline ALL           - offline all targets

    --offline tid=4         - offline target 4

                              (target with tid 4)

    --offline iqn.2008-08.com.example:some.target

                            - offline this target

```

--ready

Put all or selected targets in ready state.

```
Example usage:

    --ready ALL             - ready all targets

    --ready tid=4           - ready target 4

                              (target with tid 4)

    --ready iqn.2008-08.com.example:some.target

                            - ready this target

```

--update <value>

Update all or selected targets. The target will be updated only if it's not used (no initiator is connected to it). If you want to update targets which are in use, you have to add "--force" flag.

```
Example usage:

    --update ALL             - ready all targets

    --update tid=4           - ready target 4

                               (target with tid 4)

    --update iqn.2008-08.com.example:some.target

                             - update this target

```

-s, --show

Show all the targets.

-C, --control-port <NNNN>

It is possible to run multiple concurrent instances of tgtd on a host. This argument is used to control which instance the tgt-admin command will operate on.

-c, --conf <configuration file>

Specify an alternative configuration file instead of /etc/tgt/targets.conf, which is the default.

--ignore-errors

Continue even if tgtadm exits with non-zero code.

-f, --force

Force some operations even if the target is in use.

-p, --pretend

Only print tgtadm options which would be used; don't execute any actions. Assumes -v.

--dump

Dump current tgtd configuration. Note: does not include detailed parameters, like write caching.

-v, --verbose

Increase verbosity (show tgtadm commands used).

-h, --help

Display a list of available options and exit.

## FILES
/etc/tgt/targets.conf

Configuration file for tgt-admin.

/usr/share/doc/tgt/targets.conf.example

Example configuration file for tgt-admin.

## SEE ALSO
targets.conf(5), tgtd(8), tgtadm(8), tgtimg(8), tgt-setup-lun(8). https://github.com/fujita/tgt

## REPORTING BUGS
Report bugs to <stgt@vger.kernel.org>


tgt-setup-lun

title: tgt-setup-lun(8)

text:
# tgt-setup-lun(8)

## NAME
tgt-setup-lun - Helper script that creates a target, adds a device to the target, and defines initiators that can connect to the target

## SYNOPSIS
tgt-setup-lun -d <device> -n <targetname> [-b <bsname>] [-t <transport>] [-C <control_port>] [initiator_IP...] [-h]

## DESCRIPTION
Creates a target according to the supplied target_name. tgtd must be running. The format of the default IQN generated from the target name is: "iqn.2001-04.com.<hostname>-<target_name>", or a complete IQN may be given. The target name must be unique.

The script then adds the requested device to the target. If specific IP addresses are defined, it adds them to the list of allowed initiators for that target. If no IP addresses is defined, it defines that the target accepts any initiator.

## EXAMPLES
Create a target that uses /dev/sdb1 and allows connections only from 192.168.10.81:

```
      tgt-setup-lun -d /dev/sdb1 -n my_target 192.168.10.81

```

Create a target that uses /dev/sdb1 and allows connections only from 192.168.10.81 and 192.168.10.82:

```
      tgt-setup-lun -d /dev/sdb1 -n my_target 192.168.10.81 192.168.10.82

```

Create a target that uses /dev/sdb1 and allows connections from any initiator:

```
      tgt-setup-lun -d /dev/sdb1 -n my_target

```

Display help:

```
      tgt-setup-lun -h

```

## AUTHOR
Written by Erez Zilber

## SEE ALSO
targets.conf(5), tgtd(8), tgtadm(8), tgtimg(8), tgt-admin(8). https://github.com/fujita/tgt

## REPORTING BUGS
Report bugs to <stgt@vger.kernel.org>

## COPYRIGHT
Copyright ï¿½ Voltaire Ltd. 2008.


tgtadm

title: tgtadm(8)

text:
# tgtadm(8)

## NAME
tgtadm - Linux SCSI Target Administration Utility

## SYNOPSIS
tgtadm [OPTIONS]... [-C --control-port <port>] [-L --lld <driver>] [-o --op <operation>] [-m --mode <mode>] [-t --tid <id>] [-T --targetname <targetname>] [-y --blocksize <size>] [-Y --device-type <type>] [-l --lun <lun>] [-b --backing-store <path>] [-f --bsoflags {direct|sync}] [-S --bsopts {backing-store opt string}] [-E --bstype <type>] [-I --initiator-address <address>] [-Q --initiator-name <name>] [-n --name <parameter>] [-v --value <value>] [-P --params <param=value[,param=value...]>] [-F --force] [-h --help]

## DESCRIPTION
tgtadm is used to monitor and modify everything about Linux SCSI target software: targets, volumes, etc.

## OPTIONS
-C, --control-port <port>

It is possible to run multiple concurrent instances of tgtd on a host. This argument is used to control which instance the tgtadm command will operate on.

-y, --blocksize <size>

Block devices are created with a default block size of 512 bytes. This argument can be used to create block devices with different block sizes.

```
Example:
tgtadm --lld iscsi --mode logicalunit --op new \

       --tid <TID> --lun <LUN> \

       -b <backing-file> --blocksize=4096

```

-Y, --device-type <type>

When creating a LUN, this parameter specifies the type of device to create. Default is disk.

```
Possible device-types are:

    disk    : emulate a disk device

    tape    : emulate a tape reader

    ssc     : same as tape

    cd      : emulate a DVD drive

    changer : emulate a media changer device

    pt      : passthrough type to export a /dev/sg device

```

-E, --bstype <type>

When creating a LUN, this parameter specifies the type of backend storage to to use.

```
Possible backend types are:

    rdwr    : Use normal file I/O. This is the default for disk devices

    aio     : Use Asynchronous I/O

    rbd     : Use Ceph's distributed-storage RADOS Block Device

    sg      : Special backend type for passthrough devices

    ssc     : Special backend type for tape emulation

```

--lld <driver> --op new --mode target --tid <id> --targetname <name>

Add a new target with <id> and <name>.

--lld <driver> --op delete --mode target --tid <id>

Delete specific target with <id>. The target must have no active I_T nexus.

--lld <driver> --op delete --force --mode target --tid <id>

Delete specific target forcibly with <id>.

--lld <driver> --op show --mode target

Show all the targets.

--lld <driver> --op show --mode target --tid <id>

Show target parameters of a target with <id>.

--lld <driver> --op new --mode logicalunit --tid <id> --lun <lun> --backing-store <path> --bsopts=<backing store options>

Add a new logical unit with <lun> to specific target with <id>. The logical unit is offered to the initiators. <path> must be block device files (including LVM and RAID devices) or regular files, or an RBD image or snapshot name for --bstype rbd. lun0 is reserved for a special device automatically created.

```
Example:
If tgt is compiled with the bs_rbd backing store for
Ceph RBD images (see tgtadm --mode system --op show to
verify), set up a target mapping the rbd image named
"rbdimage", and pass options to bs_rbd:
tgtadm --lld iscsi --op new --mode logicalunit --tid 1 \
--lun 1 --bstype=rbd --backing-store=rbdimage \
--bsopts="conf=/etc/ceph/ceph.conf;id=tgt"

```

--lld <driver> --op delete --mode logicalunit --tid <id> --lun <lun>

Delete specific logical unit with <lun> that the target with <id> has.

--lld <driver> --op bind --mode target --tid <id> --initiator-address <address>

Add the address to the access lists of the target with <id>. Initiators with the address can access to the target. 'ALL' is a special address to allow all initiators to access to a target.

--lld <driver> --op bind --mode target --tid <id> --initiator-name <name>

Add the initiator's name to the access lists of the target with <id>. Initiators with the names can access to the target.

--lld <driver> --op unbind --mode target --tid <id> --initiator-address <address>

Delete the address from the access lists of the target with <id>.

--lld <driver> --op unbind --mode target --tid <id> --initiator-name <name>

Delete the initiator's name from the access lists of the target with <id>.

--lld <driver> --op update --mode target --tid <id> --name=<parameter> --value=<value>

Change the value of <parameter> of the target with <id> to <value>.

--lld <driver> --op update --mode target --tid <id> --params parameter=value<,...>

Sets/changes the value of one or more target parameters.

--lld <driver> --op update --mode logicalunit --tid <id> --lun <id> --params parameter=value<,...>

Sets/changes the value of one or more logical unit parameters.

--lld <driver> --op start --mode lld

Start the specified lld without restarting the tgtd process. Can be used to initialize lld driver in case required modules were loaded after tgtd was already executed.

--help

Display a list of available options and exits.

## LUN PARAMETERS
These parameters are only applicable for "--mode logicalunit".

vendor_id=<string>

This parameter sets the Vendor Identification string that a LUN will report in INQURY data.

product_id=<string>

This parameter sets the Product Identification string that a LUN will report in INQURY data.

product_rev=<string>

This parameter sets the Product Revision string that a LUN will report in INQURY data.

```
Example:
tgtadm --lld iscsi --mode logicalunit --op update \

       --tid <TID> --lun <LUN> \

       --params vendor_id=TGTD,product_id=VirtualHD,product_rev=0103

```

removable=<0|1>

This can be used to override/change the default setting for the removable flag. Disk devices default to non-removable while DVD and TAPE devices default to removable.

sense_format=<0|1>

This flag controls the format of sense data that the device will return. 0 = Clasic sense format, 1 = Support descriptor format.

online=<0|1>

This controls whether a device is online or not. Devices default to be online when created but can be brought offline using this parameter. Behaviour of offline devices depend on device type. An MMC/DVD device that is offline will report that there is no disk in the unit but the actual MMC/DVD unit itself can still be communicated with. All other device types will fail all I/O with a sense code of Not Ready.

```
Example:
tgtadm --lld iscsi --mode logicalunit --op update \

       --tid 1 --lun 1 \

       --params removable=1,sense_format=1,online=1

```

mode_page=<byte-string>

This parameter is used to set specific mode pages for the device and the mode page contents. Most devices default to reasonable default mode pages automatically when the LUN is created, but this allows special settings.

```
Examples:
Create mode page '2', subpage 0 and 14 bytes of data.
This is Disconnect-Reconnect mode page.
tgtadm --mode logicalunit --op update --tid 1 --lun 2 \

         --params mode_page=2:0:14:0x80:0x80:0:0xa:0:0:0:0:0:0:0:0:0:0
Create mode page '10', subpage 0 and 10 bytes of data.
This is Control Extension mode page.
tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 \

         --params mode_page=10:0:10:2:0:0:0:0:0:0:0:2:0
Create mode page '0x1c', subpage 0 and 10 bytes of data.
This is Informational Exceptions Control mode page.
tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 \

         --params mode_page=0x1c:0:10:8:0:0:0:0:0:0:0:0:0

```

readonly=<0|1>

This sets the read-only flag of a LUN. A read-only LUN will refuse any attempts to write data to it. This parameter only applies to DISK devices.

```
tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 1 \

         --params readonly=1

```

thin_provisioning=<0|1>

This controls the provisioning for the LUN. A thin-provisioned LUN is represented as a sparse file. TGTD supports provisioning type 2 for sparse files. When initiators use the SCSI UNMAP command TGTD will release the affected areas back to the filesystem using FALLOC_FL_PUNCH_HOLE. This parameter only applies to DISK devices.

Thin-provisioning works for LUNs stored on filesystems that support FALLOC_FL_PUNCH_HOLE.

When using thin-provisioning option with a block device such a SSD or ZVOL, UNMAP SCSI command discards the region from the block device.

```
tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 1 \

         --params thin_provisioning=1

```

rotation_rate=<uint32>

This sets the reported rotation rate in RPM of the LUN to the initiator. Some operating systems assume a SSD type disk when this parameter is zero. This parameter only applies to DISK devices.

```
tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 1 \

         --params rotation_rate=0

```

## SMC SPECIFIC LUN PARAMETERS
These parameters are only applicable for luns that are of type "changer" i.e. the media changer device for a DVD Jukebox or a Virtual Tape Library.

element_type=<1|2|3|4>

This controls which type of element a certain slot in the jukebox/vtl is.

```
Slot types:

 1 -> Medium Transport (picker arm)

 2 -> Storage Element

 3 -> Import/Export Element

 4 -> Data Transfer device (CD drive, tape drive, MO drive etc)

```

address=<1-65535>

This is used to create/operate on a single slot. Address specifies the slot on which to perform the operation.

start_address=<1-65535>,quantity=<1--65535>

This is used to create/operate on an entire range of slots at once. Start_address specifies the first address to operate on and quantity specifies the number of consequtive slots.

sides=<1|2>

When creating storage elements, i.e. "element_type=2", this parameter specifies if the media has 1 or two sides to hold data.

clear_slot=<1>

This option is used to clear a storage element and remove any media that may be present. Once this command completes the storage element will show up as "Empty".

barcode=<string>

This is used to assign a barcode to an element. Barcodes are limited to 10 characters in tgtd.

volume_tag=<string>

This is used to assign a volume tag to SMC storage elements. If no volume tag is specified tgtd will use fall back to the barcode. The volume tag can be up to 32 characters.

media_home=<string>

This parameter specifies a directory where all virtual media for the dvd/tape device elements are stored. To assign a media image file to a storage element slot, you assign "barcode" to be the name of the image file in the "media_home" directory.

```
Example: How to create a DVD jukebox with eight disk trays and
two empty DVD-R disks.
# Create a target
tgtadm --lld iscsi --mode target --op new --tid 1 --targetname iqn.2007-03:virtual-dvd:`hostname`
# Create a DVD drive and give it a nice name
# The dvd starts out without a backing store file, i.e. no disk loaded
tgtadm --op new --mode logicalunit --tid 1 --lun 1 --device-type cd
tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 1 --params vendor_id=STGT_DVD,product_id=DVD101,product_rev=0010,scsi_sn=STGTDVD01,removable=1
# We need a backend store file for the media changer
if [ ! -f $HOME/smc ]; then
	dd if=/dev/zero of=$HOME/smc bs=1k count=1
fi
# Create the SMC device and give it a nice name
tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 --backing-store $HOME/smc --device-type changer
tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params vendor_id=STK,product_id=L700,product_rev=0010,scsi_sn=XYZZY_0,removable=1
# Add a Data Transfer devices (1 drive)
tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=4,start_address=1,quantity=1
# Specify that the DVD above (LUN 1) is the data transfer device we created
tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=4,address=1,tid=1,lun=1
# Medium Transport Elements (robot arm / picker)
tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=1,start_address=16,quantity=1
# define path to virtual media
VTL=${HOME}/vtl
mkdir -p ${VTL}
tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params media_home=${VTL}
# Storage Elements - 8 starting at addr 1024
tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=2,start_address=1024,quantity=8
# Add 'media' to slots 1 and 2 and leave the other 6 slots empty
# slot 1
# Create empty writeable virtual DVD-R media
tgtimg --op new --device-type cd --type dvd+r --file ${VTL}/DISK_001
tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=2,address=1024,barcode=DISK_001,volume_tag="A blank disk",sides=1
# slot 2
tgtimg --op new --device-type cd --type dvd+r --file ${VTL}/DISK_002
tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=2,address=1025,barcode=DISK_002,volume_tag="My second blank disk",sides=1
# Allow ALL initiators to connect to this target
tgtadm --lld iscsi --mode target --op bind --tid 1 --initiator-address ALL
# Show all our good work.
tgtadm --lld iscsi --mode target --op show

```

## PASSTHROUGH DEVICES
In addition to device emulation TGTD also supports utilizing existing SG devices on the host and exporting these through a special passthrough device type.

--bstype=sg

This specifies that an SG devices is used.

--device-type=pt

This specifies that passthrough device type is used.

--backing-store=</dev/sg4>

This specifies which device to export through TGTD.

--bsoflags={direct|sync}

This argument is used when creating a LUN to specify extra flags to use when opening the backing file. O_DIRECT is specified by "direct" and O_SYNC by "sync".

```
Example:
Make /dev/sg4 available to initiators connecting to TGTD.
tgtadm --lld iscsi --op new --mode logicalunit --tid 1 --lun 1 --bstype=sg --device-type=pt --backing-store=/dev/sg4
Example:
Open the backing file with O_SYNC.
tgtadm --lld iscsi --op new --mode logicalunit --tid 1 --lun 1 --bsoflags="sync" --backing-store=/data/100m_image.raw

```

## HEADER DIGEST AND DATA DIGEST
Header and data digests can be set on a per target parameter. TGTD supports two modes, None and CRC32C. When the digest is set to None, TDTD will negotiate that digests will not be used, and when CRC32C is set, TGTD will force the connection to use digest.

### Viewing the current settings
This command is used to view the current settings for header/data digest.

```
tgtadm --op show --mode target --tid 1

  ...

  HeaderDigest=None

  DataDigest=None

  ...

```

### Setting digest

```
Set header digest to CRC32C:
tgtadm --op update --mode target --tid 1 -n HeaderDigest -v CRC32C
Set data digest to None:
tgtadm --op update --mode target --tid 1 -n DataDigest -v None

```

## CHAP AUTHENTICATION
CHAP authentication is supported to require authentication before an initiator is allowed to log in and access devices.

CHAP main-phase authentication is set on the target level. To set up CHAP authentication we first need to create an account and its associated password, then we bind the account to one or more targets.

### Setting CHAP on a target
These two commands create a user account and binds it to target 1.

```
tgtadm --lld iscsi --op new --mode account --user ronnie --password password
tgtadm --lld iscsi --op bind --mode account --tid 1 --user ronnie

```

### List all accounts
This command is used to list all accounts that have been created.

```
tgtadm --lld iscsi --op show --mode account
Account list:

    ronnie

```

### Show if a target requires authentication
When listing the targets, each target that has authantication enabled will contain a listing of all accoutns bound to that target.

```
tgtadm --lld iscsi --op show --mode target
Target 1: iqn.ronnie.test
...
Account information:

    ronnie
...

```

## NOP-OUT PROBES
TGTD can send NOP-OUT probes to connected initiators to determine when an initiator is dead and then automatically clear and tear down the TCP connection. This can either be set as a global default from the tgtd command-line or it can be set for individual targets using the tgtadm command.

### Check the current NOP-OUT setting
The tgtadm command is used to view the current setting for if/when to send NOP-OUT probes to connected initiators.

If the target is configured to send NOP-OUT probes this will show up as two parameter lines in the target printout. If the target is not configured to send NOP-OUT these lines will not be printed at all.

```
tgtadm --lld iscsi --op show --mode target
Target 1: iqn.ronnie.test

    System information:

        Driver: iscsi

        State: ready

        Nop interval: 5

        Nop count: 5

    I_T nexus information:

```

### Setting NOP-OUT for a target
The tgtadm command is used to change the NOP-OUT settings.

```
tgtadm --op update --mode target --tid 1 -n nop_count -v 5
tgtadm --op update --mode target --tid 1 -n nop_interval -v 5

```

## ISCSI PORTALS
iSCSI portals can be viewed, added and removed at runtime.

### List portals
This command is used to list the current iSCSI portals defined on the target:

```
tgtadm --lld iscsi --op show --mode portal
Portal: 10.1.1.101:3260,1
Portal: 127.0.0.1:3260,1

```

### Add portal
This command is used to add a portal to the target :

```
tgtadm --lld iscsi --op new --mode portal --param portal=10.1.1.101:3260

```

### Remove portal
This command is used to remove a portal from the target :

```
tgtadm --lld iscsi --op delete --mode portal --param portal=10.1.1.101:3260

```

## ISCSI CONNECTIONS
iSCSI connections can be viewed and forced closed at runtime.

### List all active connections for a target
This command is used to list the all the active iSCSI connections to the target with connection id, initiator name and ip address for the initiator :

```
tgtadm --lld iscsi --op show --mode conn --tid 1
Session: 2

    Connection: 0

        Initiator: iqn.2008-11.org.linux-kvm:

        IP Address: 127.0.0.1

```

### Close an existing connection
This command is used to close an iSCSI connection. Note that forcibly closing iSCSI connections can lead to data-loss.

```
tgtadm --lld iscsi --op delete --mode conn --tid 1 --sid 2 --cid 0

```

## ONLINE/OFFLINE STATUS
Tgtd LUNs can be in online or offline status. LUNs that are Offline behave slightly different depending on the device type. Offline devices behave as if there is no media available and any operations that access media will fail with an check-condition error.

Devices can not be set to Offline mode while there are "PREVENT ALLOW MEDIUM REMOVAL" locks on the device. Similarly media in Online devices can not be software ejected while there are such locks on the device (the 'eject' command will fail).

### Show Online/Offline status
Finding the Online/Offline status of a LUN is done through the tgtd command. If "Prevent removal" is "Yes" this indicates that an application holds a "prevent media removal" lock on the device.

```
tgtadm --lld iscsi --mode target --op show
...

        LUN: 2

            Type: cd/dvd

            SCSI ID: IET     00010002

            SCSI SN: beaf12

            Size: 3432 MB, Block size: 1

            Online: Yes

            Removable media: Yes

            Prevent removal: Yes
...

```

### Changing a LUN to Offline
A LUN is changed to Offline status using the tgtadm command. When devices are set Offline these devices will behave as if there is no media loaded into the drive.

Change a LUN to become offline. (no disk in the drive)

```
tgtadm --tid 1 --lun 2 --op update --mode logicalunit -P Online=No

```

## ISNS PARAMETERS
iSNS configuration for a target is by using the tgtadm command.

iSNSServerIP

This specifies the IP address of the iSNS server. TGTD only supprots one iSNS server.

```
Example:
tgtadm --op update --mode sys --name iSNSServerIP --value 192.168.11.133

```

iSNS

This setting enables(on)/disables(off) iSNS.

```
Example:
tgtadm --op update --mode sys --name iSNS --value On

```

iSNSServerPort

This setting specifies the port to use for iSNS.

```
Example:
tgtadm --op update --mode sys --name iSNSServerPort --value 3205

```

iSNSAccessControl

Enable/disable access control for iSNS.

```
Example:
tgtadm --op update --mode sys --name iSNSAccessControl --value Off

```

## SEE ALSO
tgtd(8), tgt-admin(8), tgtimg(8), tgt-setup-lun(8). https://github.com/fujita/tgt

## REPORTING BUGS
Report bugs to <stgt@vger.kernel.org>


tgtd

title: tgtd(8)

summary: The SCSI Target Daemon

text:
# tgtd(8)

## NAME
tgtd - The SCSI Target Daemon

## SYNOPSIS
tgtd

tgtd [-C --control-port <INTEGER>] [-d --debug <INTEGER>] [-f --foregound] [-h --help] [--iscsi <...>]

## DESCRIPTION
Tgtd is a SCSI Target daemon. It can be used to provide SCSI target service to a network. The most common service is iSCSI but other services are also supported.

## DEVICE TYPES
Tgtd provides support for both emulated and passthrough of real devices.

```
    Tgtd can emulate the following types of devices:

    disk       : Normal disk device. Emulates a SCSI harddisk.

    tape       : Tape device. Emulates a SCSI tape drive.

    cd         : CD device. Emulates a SCSI DVD burner.

    changer    : Media changer. Emulate the changer device for a virtual tape library or DVD jukebox.

```

## OPTIONS
-d --debug <INTEGER>

Set to non-zero value to activate additional debugging messages to be logged.

-f --foreground

Run the daemon in the foreground.

-h --help

Print help text to the screen.

-C --control-port <INTEGER>

This comamnd is used to specify the control port to use for this instance of tgtd. This allows to run multiple instances of TGTD on a host. TGTADM has a matching argument to control which instance to connect to.

--iscsi <...>

ISCSI specific options. See the ISCSI section below for options specific to this frontend.

## ISCSI OPTIONS
These parameters apply only to the iSCSI frontend.

### portal=<ip-address[:port]>
This option is used to bind tgtd to a specific ip-address/portal and/or port. By default tgtd will bind to port 3260 on the wildcard address. The ip-address part (before the ":") can be missing to designate the wildcard address with a none-default port.

Example: to bind tgtd to a specific address and port

```
	tgtd --iscsi portal=192.0.2.1:3260

```

Example: to bind tgtd to any address but a none-default port

```
	tgtd --iscsi portal=:3251

```

### nop_interval=<integer>
This sets the default interval for sending NOP-OUT to probe for connected initiators. This parameter only controls the default value for targets. Individual targets can be controlled using tgtadm.

The default value is 0 which means that the feature is disabled TGTD will not send any NOP-OUT probes.

### nop_count=<integer>
This sets the default value for after how many failed probes TGTD will consider the initiator dead and tear down the session. This parameter only controls the default value for targets. Individual targets can be controlled using tgtadm.

The default value is 0.

Example: send NOP-OUT every 5 seconds and abort the session after 6 failures.

```
	tgtd --iscsi portal=192.0.2.1:3260,nop_interval=5,nop_count=6

```

## ENVIRONMENT VARIABLES

### TGT_IPC_SOCKET=<path>
When set tgtd and tgtadm will use the specified path as the IPC socket instead of the default '/var/run/tgtd/socket.0'

## SEE ALSO
targets.conf(5), tgtadm(8), tgt-admin(8), tgtimg(8), tgt-setup-lun(8). https://github.com/fujita/tgt

## COPYRIGHT/LICENSE

```
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, see http://www.gnu.org/licenses/.
```


tgtimg

title: tgtimg(8)

text:
# tgtimg(8)

## NAME
tgtimg - Linux SCSI Target Framework Image File Utility

## SYNOPSIS
tgtimg [-o --op <operation>] [-Y --device-type <device-type>] [-b --barcode <barcode>] [-s --size <size>] [-t --type <media-type>] [-f --file <path>] [-T --thin-provisioning]

tgtimg --help

## DESCRIPTION
Tgtimg is a utility to create and manage the image files used by the TGTD device emulation.

This command is used to initialize device image files with the additional metadata, such as barcode, list of blocks, total size, etc that the TGTD emulation needs.

## OPTIONS
-h, --help

Show a help screen and exit.

-o, --op {new|show}

Operation. Is either new to create a new image file or show to show the content of an existing image file.

-Y, --device-type <type>

This specifies the type of image file.

```
Supported device types are :

    cd   : to create media for a dvd device

    disk : to create media for a disk device

    tape : to create media for a tape device

```

-t, --type <media-type>

When creating a new image, this specifies the type of media to emulate. The available mediatypes depend on the type of the device.

```
Supported media types for cd devices are :

    dvd+r : create a blank writeable DVD+R disk
Supported media types for disk devices are :

    disk  : create an empty disk
Supported media types for tape devices are :

    data  : create a normal data tape

    clean : create a cleaning tape

    worm  : create a worm

```

-b, --barcode <barcode>

When creating a new image, this argument specifies the barcode to use with this image file. Backup application software often uses barcodes to identify specific tapes. When emulating a VTL, make sure that all tape images use unique barcodes.

-s, --size <size>

When creating a new image, this specifies the size in megabytes for the virtual tape image.

-f, --file <path>

The filename of the image file.

-T, --thin-provisioning

This argument makes the allocation of the image format use thin-provisioning. This means that the file created will be a sparse file that will allocate blocks from the filesystem on demand. Be careful when using thin-provisioning. If the filesystem fills up a iSCSI write to a thin-provisioned LUN can fail. Initiators generally do not handle "out of space" errors gracefully.

Thin-provisioning uses FALLOC_FL_PUNCH_HOLE which is only available on some linux filesystems. Thin-provisioning can only be used for DISK images.

## EXAMPLES
To create a new 100MByte disk

```
      tgtimg --op new --device-type disk --type disk --size 100 --file /data/hd001.raw

```

To create a new tape image

```
      tgtimg --op new --device-type tape --barcode 12345 --size 100 --type data --file /data/tape001.img

```

To view the content of an existing image

```
      tgtimg --op show --device-type tape --file /data/tape001.img

```

To create a new blank DVD+R image

```
      tgtimg --op new --device-type cd --type dvd+r --file /data/dvd001.iso

```

## SEE ALSO
tgtd(8), tgtadm(8), tgt-admin(8), tgt-setup-lun(8). https://github.com/fujita/tgt

## REPORTING BUGS
Report bugs to <stgt@vger.kernel.org>


package: sdparm

title: sas_disk_blink(8)

summary: blink the LED on a SAS disk

text:
# sas_disk_blink(8)

## NAME
sas_disk_blink - blink the LED on a SAS disk

## SYNOPSIS
sas_disk_blink [--help] [--set NUM] [--verbose] DEVICE

## DESCRIPTION
This bash shell script attempts to blink the LED on the SAS disk referred to by DEVICE. By default the LED will blink for 30 seconds. This is meant to help identify which disk corresponds to a given DEVICE.

The script use the sdparm utility and manipulates the "Ready LED Meaning" (RLM) field in the Protocol specific port mode page in order to blink the LED.

## OPTIONS
Arguments to long options are mandatory for short options as well.

-h, --help

print out the usage message then exit.

-s, --set NUM

when NUM is 0 then the RLM field is cleared. When NUM is 1 then the RLM field is set. When NUM > 1 then the SAS disk LED is made to blink for NUM seconds. If this option is not given then the SAS disk LED is made to blink for 30 seconds.

-v, --verbose

increase level or verbosity.

## EXIT STATUS
The exit status of this script is 0 when it is successful. Otherwise the exit status is that of the last sdparm utility called. See the sdparm(8) man page.

## AUTHORS
Written by D. Gilbert

## COPYRIGHT
Copyright © 2013-2016 Douglas Gilbert

This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
sdparm (sdparm)


title: scsi_ch_swp(8)

text:
# scsi_ch_swp(8)

## NAME
scsi_ch_swp - change SCSI Software WRITE Protect and block device settings

## SYNOPSIS
scsi_ch_swp [--help] [--set 0|1] [--verbose] [--wr] BLK_DEVICE

## DESCRIPTION
This bash shell script attempts to read or change the Software Write Protect (SWP) bit in the SCSI Control mode page using the sdparm utility. If that change is successful then it uses the blockdev utility to change BLK_DEVICE's read-write or read-only setting in sympathy. This script is only available in Linux since the blockdev utility is Linux specific.

If changing the SWP bit is supported, setting the SWP bit makes BLK_DEVICE read-only at the device (disk) itself. Clearing the SWP bit makes BLK_DEVICE read-write which is usually the default setting at device (disk) power up.

If no options are given then the current state of the SWP bit is printed out (using sdparm) together with blockdev's RO bit. If they are both 1 then BLK_DEVICE is in read-only mode; if they are both 0 then BLK_DEVICE is in read-write mode.

## OPTIONS
Arguments to long options are mandatory for short options as well.

-h, --help

print out the usage message then exit.

-s, --set 0|1

when 0 is given then the SWP bit in the Control mode page is cleared (i.e. set that bit to 0) using sdparm; and blockdev is used to set BLK_DEVICE to read-write mode. When 1 is given then the SWP bit in the Control mode page is set using sdparm; and blockdev is used to set BLK_DEVICE to read-only mode. The default (i.e. when this option is not given) is to read the state of the SWP bit and BLK_DEVICE's read-only mode and print those values out.

-v, --verbose

increase level or verbosity.

-w, --wr

when the BLK_DEVICE is in read-only mode, Linux will not typically allow BLK_DEVICE to be opened read-write by sdparm, so the default action of this script is to use the sdparm --readonly option when --set 0 has been invoked. It is possible that BLK_DEVICE could be a generic device (e.g. /dev/sg3) which has a different interpretation of the read-only open flag and may fail. For such rare cases the --wr option makes sdparm open BLK_DEVICE read-write when --set 0 is invoked.

## EXIT STATUS
The exit status of this script is 0 when it is successful. Otherwise the exit status is that of the sdparm or the blockdev utility, whichever is called last. See the sdparm(8) man page.

## AUTHORS
Written by D. Gilbert

## COPYRIGHT
Copyright © 2013 Douglas Gilbert

This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
sdparm(sdparm), blockdev(8)