Admin commands

Phobos provide both an Application Programming Interface and a Command Line Interface for users. Within them, commands and functions are separated between store commands and admin commands.

In this page, we will detail the admin commands, which are mainly wrappers around the API functions, and pointers to the API will be given when their CLI counterpart are evoked. However, we will we will not detail the API functions here.

As a side note though, to use the API, you should:

• Include the header file phobos_admin.h
• Link with the library libphobos_admin (using -lphobos_admin)
• Link with the glib-2 dependency (using -lglib-2.0)

Launching phobosd

To use phobos, a daemon called phobosd needs to be launched. It mainly manages the drive/media allocation and sets up resources to read or write your data.

To launch/stop the daemon:

# systemctl start/stop phobosd

To test that the daemon is currently running, Phobos provides the phobos ping command:

phobos ping

The API function for the ping is phobos_admin_ping().

Scanning libraries

Use the phobos lib scan command to scan a given library. Its API counterpart is the phobos_admin_lib_scan() function. For instance, the following will give the contents of the /dev/changer library:

phobos lib scan /dev/changer

Adding media

To add a medium, you can use the add commands provided for each type of resource (currently dir, tape and rados_pool):

phobos dir add /tmp/dummy
phobos tape add dummy
phobos rados_pool add dummy

Additionally, when adding a medium, you can specify a set of tags to give information or differentiate media by using the --tags option. For instance:

phobos dir add --tags foo,bar /tmp/dummy

Note: There is currently no API functions for adding any type of medium, they are located in the DSS API, as the dss_media_set() generic function.

Tape specific options

When adding a tape, you must also specify a --type which corresponds to the tape technology. Also, you can specify a --fs option, which will indicate the filesystem type used on the tape. It defaults to LTFS. For instance:

phobos tape add --tags lto5 --fs LTFS P00000L5

Adding device

To add a device, you can use the add commands provided for each type of resource (currently dir, drive and rados_pool):

phobos dir add /tmp/dummy
phobos drive add /dev/dummy
phobos rados_pool add dummy

The API counterpart of these commands is the phobos_admin_device_add() function.

It is recommended to specify a device path which is persistent after reboot (eg. managed by dev mapper).

Note: the commands to add a directory and a rados_pool both add these two resources as their own medium and device, meaning to add a dir/rados_pool medium and a dir/rados_pool device, you only have to do the above command once. However, as tapes can be read by different drives, they are two separate resources, and you must add each individually.

Resource lock

The two commands explained below (lock and unlock) are asynchronous by default: the resource status is updated in the database, then the daemon is notified for a device update.

Locking resources

A device or media can be locked using their lock commands. If locked, they cannot be used for subsequent 'put' or 'get' operations. For instance:

phobos drive lock /dev/dummy
phobos dir lock /tmp/dummy

For devices, the 'lock' command accepts a --wait option, which waits for the complete release of the drive by the daemon before returning.

Note: For devices, the API function is phobos_admin_device_lock(), and for media, there is currently no API function available.

Unlocking resources

By default, when a resource (dir, tape, drive, rados_pool) is added in the system, it is considered locked. To unlock them, either use:

• the --unlock option of their add command:

phobos rados_pool add --unlock dummy

• in the case of media, the --unlock option of their format command, as explained in the Formatting media section.
• their unlock command, for instance:

phobos tape unlock dummy
phobos rados_pool unlock dummy

The command can also take a --force option, which will force the unlocking the resource, even if it is in use.

Note: For devices, the API function is phobos_admin_device_unlock(), and for media, there is currently no API function available.

Formatting media

By default, when a medium (dir, tape, rados_pool) is added in the system, it is considered blank, and thus unusable. To change this status, it has to be formatted:

phobos tape format [073200-073222]L6

You can optionally unlock the tape when the operation is done by using the --format option.

Phobos can also format multiple media at the same time (provided there are enough devices to do so), and you can limit that number using the --nb-streams option:

phobos tape format --unlock --nb-streams 3 [073200-073222]L6

With this command, a maximum of 3 requests for media formatting will be sent at a time, and the client will wait a format is done before sending another. If nothing or 0 is specified, no limit is applied.

Migrating drives

Phobos allows changing the host of drive by using the phobos drive migrate command. Drives information will be updated only if they are not currently used by the system i.e. no daemon is using them.

For instance:

phobos drive migrate host2 /dev/mapper/LT06-012345

The associated API function is phobos_admin_drive_migrate().

Removing drives

Phobos allows the removal of drives from its system, by using the phobos drive delete command, and its API counterpart phobos_admin_device_delete(). For instance:

phobos drive delete /dev/mapper/LT06-012345

Drives will be removed only if they are not currently used by the system i.e. no daemon is using them.

Querying the status of the drives

In order to have a complete view of the drives (which tape is loaded, ongoing I/Os, etc.) a query can be sent to the daemon through:

phobos drive status
|   address | device   | media    | mount_path      | name     | ongoing_io   |     serial |
|-----------|----------|----------|-----------------|----------|--------------|------------|
|         6 | /dev/sg7 |          |                 | /dev/st6 |              | 1933008059 |
|         7 | /dev/sg8 | Q00000L6 | /mnt/phobos-sg8 | /dev/st7 | False        | 1291610660 |

address is the drive index as shown by mtx status. ongoing_io can be either true or false indicating whether an I/O is ongoing on the corresponding drive.

The API function for this is phobos_admin_device_status().

Setting access

Media can be set to accept or reject some types of operation. We distinguish three kinds of operation: put (P), get (G) and delete (D).

# Set medium access: allow get and delete, forbid put
phobos tape set-access GD 073000L8

# Add access: add put and get (delete is unchanged)
phobos dir set-access +PG /path/to/dir

# Remove access: remove put (get and delete are unchanged)
phobos tape set-access -- -P 073000L8

Tagging resources

Phobos implements a flexible mechanism to partition storage resources into (possibly overlapping) subsets.

This mechanism is based on tags.

Multiple tags can be associated to the storage media at creation time or later on:

# Add media with tags "class1" and "project2"
phobos tape add --tags class1,project2 --type LTO8 [073000-073099]L8

# Update tags for these tapes
phobos tape update --tags class2 [073000-073099]L8

# Clear tags
phobos dir update --tags '' [073000-073099]L8

Media can be listed following their tags:

phobos tape list --tags class1,project2

When pushing objects to phobos, you can then restrict the subset of resources that can be used to store data by specifying tags with the --tags option.

# The following command will only use media with tags 'class1' AND 'projX'
phobos put --tags class1,projX /path/to/obj objid

• If several tags are specified for put, phobos will only use media having all of the specified tags.
• A media is selected if its tags include the tags specified for the put operation.

The following table illustrates conditions for matching tags:

put tags	media tags	match
(none)	(none)	yes
(none)	A,B	yes
A	A,B	yes
A,B	A,B	yes
A,B,C	A,B	no
A	(none)	no
C	A,B	no
A,C	A,B	no

Locating media

Phobos allows you to locate its media by answering you on which host you should execute phobos commands or calls that require access to a specific medium.

phobos tape locate 073000L8
phobos dir locate /path/to/dir

Media families

For now, phobos supports 2 families of storage devices: tapes and directories.

• Tapes are media accessed by drives.
  • Drives are managed by phobos drive ... commands
  • Tapes are managed by phobos tape ... commands
• Directories are self-accessible. They do not need drives to be read.
  • Directories are managed by phobos dir ... commands.

To specify the default family where data is to be written, specify it in the phobos configuration file:

[store]
# indicate 'tape' or 'dir' family
default_family = tape

Alternatively, you can override this value by using the '--family' option of your put commands:

# put data to directory storage
phobos put --family dir file.in obj123

Storage layouts

For now, phobos only supports the 'raid1' storage layout, for mirroring.

The 'simple' storage layout can be obtained by modifiying the number of replicas to 1.

The default layout to use when data is written can be specified in the phobos configuration file, in case multiple are defined:

[store]
default_layout = raid1

If an alias is defined, you can set it as default instead of the layout:

[store]
default_alias = simple

[alias "simple"]
layout = raid1
lyt-params = repl_count=1

Alternatively, you can override this default value by using the 'right' option in your put commands:

# put data using a raid1 layout
phobos put --layout raid1 file.in obj123

phobos dir add --unlock dummy
phobos tape add --unlock dummy
phobos drive add --unlock dummy
# put data using a simple alias
phobos put --alias simple file.in obj123

Layouts can have additional parameters. For now, the only additional parameter is the number of replicas for raid1. This is for now specified using the following env variable:

# put data using a raid1 layout with 3 replicas
PHOBOS_LAYOUT_RAID1_repl_count=3 phobos put --layout raid1 file.in obj123

Configuring device and media types

Supported tape models

The set of tape technologies supported by phobos can be modified by configuration.

This list is used to verify the model of tapes added by administrators.

[tape_model]
# comma-separated list of tape models, without any space
# default: LTO5,LTO6,LTO7,LTO8,T10KB,T10KC,T10KD
supported_list = LTO5,LTO6,LTO7,LTO8,T10KB,T10KC,T10KD

Listing resources

Any device or media can be listed using the 'list' operation. For instance, the following will list all the existing tape identifiers:

phobos tape list

The 'list' output can be formatted using the --output option, following a list of comma-separated attributes:

phobos tape list --output stats.phys_spc_used,tags,adm_status

If the attribute 'all' is used, then the list is printed with full details:

phobos tape list --output all

Other options are available using the --help option.