Admin commands

Phobos provides 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)

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

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

Ping the daemon

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

Add a device or medium to the system

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

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 --type 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 management

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.

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

There is currently no API function for this.

Concurrency lock cleaning

As part of its internal functioning, Phobos uses lock for managing resources concurrently. They are different from the locks admins can pose on resources to prevent their usage altogether.

To clean the first type of locks that may still exist after a daemon crash for instance, use the phobos lock clean command. Its API counterpart is the phobos_admin_clean_locks() function.

By default, if the locks to clean belong to a host on which there is an active Phobos daemon, the command will fail.

This command has multiple parameters available:

--force to clean locks even if the daemon is online,
--global to clean every lock either on all host if given alongside --force or owned by the local host,
--type to clean locks of a certain type, which are currently either device, media, object or media_update,
--family to clean locks of a certain family, either dir or tape,
--ids to clean specific locks.

Here are some examples of the command:

phobos lock clean --type media --family dir --global --force
phobos lock clean --type object --ids 3
phobos lock clean --global --force --type media_update --ids 2 3
phobos lock clean --type media_update --family tape

Tagging media

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

There is no API function for this as of yet.

Information retrieval

Locating medium

Phobos allows you to locate a medium by answering you on which host you should execute Phobos commands or calls that require access to a specific medium. For instance:

$ phobos tape locate 073000L8
localhost

$ phobos dir locate /path/to/dir
other_host

The associated API function is phobos_admin_medium_locate().

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().

Listing devices and media

Any device or media can be listed using the 'list' operation. For instance:

$ phobos tape list
073000L8
073001L8

Moreover, these commands have multiple options available:

--output <column_name> to only show the given attributes of the outputted objects (if not given, will only output the names, if given all, will output every attribute),
--format <format> to output information in the specified format, defaults to "human",
for media, --tags <tags_list> to filter them based on their annoted tags,
for drives, --model <model> to filter on the drive models.