Chapter 9. Managing storage volumes in GNOME

This section describes how you can manage storage volumes in GNOME with a virtual file system. GNOME Virtual File System (GVFS) is an extension of the virtual file system interface provided by the libraries the GNOME desktop is built on.

9.1. The GVFS system

The GVFS provides complete virtual file system infrastructure and handles storage in the GNOME desktop. It uses addresses for full identification based on the URI (Uniform Resource Identifier) standard, syntactically similar to URL addresses in web browsers. These addresses in the form of schema://user@server/path are the key information determining the kind of service.

The GVFS helps to mount the resources. These mounts are shared between multiple applications. Resources are tracked globally within the running desktop session, which means that even if you quit an application that triggered the mount, it continues to be available for any other application. Multiple applications can access the mount at the same time unless it is limited by a back end. Some protocols by design permit only a single channel.

GVFS mounts removable media in the /run/media/ directory.

9.2. The format of the GVFS URI string

You must form a URI string to use back end services. This string is a basic identifier used in GVFS, which carries all necessary information needed for unique identification, such as type of service, back end ID, absolute path, or user name if required. You can see this information in the Files address bar and GTK+ open or save file dialog.

The following example is a very basic form of the URI string and points to a root directory (/) of the FTP (File Transfer Protocol) server running at ftp.myserver.net domain:

Example: URI string pointing to the root FTP directory

ftp://ftp.myserver.net/

Example: URI string pointing to a text file

ssh://joe@ftp.myserver.net/home/joe/todo.txt

9.3. Mounting a storage volume in GNOME

In virtual file systems, particular resources are set to be mounted automatically, but the most common way is to trigger mounts manually.

Procedure

  1. Open the Files application.
  2. Press Ctrl+L to view the location bar.
  3. Enter a well-formed URI string.

    Alternatively, Files provides the Connect to server dialog, which you can find in Other locationsConnect to server.

  4. When asked for login credentials, enter your name and password into the relevant entry boxes.
  5. When the mounting process finishes, you can start working with the storage volume.

9.4. Unmounting a storage volume in GNOME

You can eject or unmount resources using the following procedure.

Procedure

  1. Click the Eject icon on the chosen mount.
  2. Wait until the mount disappears or notification about the safe removal appears.

9.5. Overview of FUSE daemon in GVFS

Applications built with the GIO library can access GVFS mounts. In addition, GVFS provides a FUSE daemon which exposes active GVFS mounts. Any application can access active GVFS mounts using the standard POSIX APIs as though mounts were regular file systems.

In certain applications, additional library dependency and new virtual file system (VFS) subsystem specifics might be unsuitable or too complicated. For such reasons and to boost compatibility, GVFS provides a File System in Userspace (FUSE) daemon, which exposes active mounts through its mount for standard Portable Operating System Interface (POSIX) access. This daemon transparently translates incoming requests to imitate a local file system for applications.

Important

You might experience difficulties with certain combinations of applications and GVFS back ends.

The FUSE daemon starts automatically with the gvfs master daemon and places its mount either in the /run/user/UID/gvfs/ or ~/.gvfs/ files as a fallback. Manual browsing shows individual directories for each GVFS mount. The system passes the transformed path as an argument when you are opening documents from GVFS locations with non-native applications. Note that native GIO applications automatically translate this path back to a native URI.

9.6. GIO tools and xdg-utils in GNOME

GIO provides several commands that might be useful for scripting or testing. Here is a set of POSIX commands counterparts as follows:

Commands

Description

gio cat

Displays the content of a file.

gio mkdir

Creates a new directory.

gio rename

Renames a file.

gio mount

Provides access to various aspects of the gio mounting functionality.

gio set

Sets a file attribute on a file.

gio copy

Makes a copy of a file.

gio list

Lists directory contents.

gio move

Moves a file from one location to another.

gio remove

Removes a file.

gio trash

Sends files or directories to the Trashcan. This can be a different folder depending on where the file is located, and not all file systems support this concept. In the common case that the file lives inside a user’s home directory, the trash folder is $XDG_DATA_HOME/Trash.

gio info

Displays information of the given locations.

gio save

Reads from standard input and saves the data to the given location.

gio tree

Lists the contents of the given locations recursively, in a tree-like format. If no location is given, it defaults to the current directory.

Following additional commands provide more control of GIO specifics:

gio monitor

Monitors files or directories for changes, such as creation, deletion, content and attribute changes, and mount and unmount operations affecting the monitored locations.

gio mime

Lists the registered and recommended applications for the mimetype if no handler is given, else, it is set as the default handler for the mimetype.

gio open

Opens files with the default application that is registered to handle files of this type.

Note

For user convenience, bash completion is provided as a part of the package.

All these commands are native GIO clients, there is no need for the fallback FUSE daemon to be running. Their purpose is not to be drop-in replacements for POSIX commands, in fact, a very little range of switches is supported. In their basic form, these commands take an URI string as an argument instead of a local path.

This all allows GNOME to be well-supported within xdg-tools, a freedesktop.org interoperability project. For example, the xdg-open utility calls gio open when a running GNOME session is detected, and reads the file type associations from the correct location.

Additional resources

  • The gio(1) man page.

9.7. Executing the GIO commands

The following are a few examples of the GIO commands usage:

  • To lists all files in /tmp on a local file system, run:

    $ gio list file:///tmp
  • To list contents of a text file from a remote machine:

    $ gio cat ssh://joe@ftp.myserver.net/home/joe/todo.txt
  • To copy the referenced text file to a local /tmp directory, run:

    $ gio copy ssh://joe@ftp.myserver.net/home/joe/todo.txt /tmp/

Additional resources

  • The gio man page.

9.8. Overview of GVFS Metadata

The GVFS metadata storage is implemented as a set of key-and-value pairs that bind information to a particular file. Thus, there is a tool for a user or application to save small data designed for runtime information such as icon position, last-played location, position in a document, emblems, notes, and so on.

Whenever you move a file or directory, GVFS moves the metadata accordingly so that metadata stays connected to the respective file. The GVFS stores all metadata privately, so metadata is available only on the machine. However, GVFS tracks mounts and removable media as well.

Note

GVFS mounts removable media in the /run/media/ directory.

To view and manipulate with metadata, you can use:

  • the gio info command,
  • the gio set command, or
  • any other native GIO way of working with attributes.

Additional resources

  • The gio man page.

9.9. Setting custom GIO metadata attribute

This procedure describes how to set a custom metadata attribute.

Notice the differences between particular gio info calls and data persistence after a move or rename (note the gio info command output):

Procedure

  1. Create an empty file.

    $ touch /tmp/myfile
  2. View the metadata of this file.

    $ gio info -a 'metadata::*' /tmp/myfile
    uri: file:///tmp/myfile
    attributes:
  3. Set a string to this file.

    $ gio set -t string /tmp/myfile 'metadata::mynote' 'Please remember to delete this file!'
  4. View the metadata.

    $ gio info -a 'metadata::*' /tmp/myfile
    uri: file:///tmp/myfile
    attributes:
      metadata::mynote: Please remember to delete this file!
  5. Move this file to a new location.

    $ gio move /tmp/myfile /tmp/newfile
  6. View the metadata.

    $ gio info -a 'metadata::*' /tmp/newfile
    uri: file:///tmp/newfile
    attributes:
      metadata::mynote: Please remember to delete this file!

    The metadata persists when you move the file using the GIO API.

Additional resources

  • The gio man page.

9.10. Password management of GVFS mounts

A typical GVFS mount authenticates on its activation unless the resource allows anonymous authentication or does not require any authentication at all. In a standard GTK+ dialog, you can choose to store or not to store the password.

When you select the persistent storage, the password is stored in the user keyring. GNOME Keyring is a central place for secrets storage. The password is encrypted and automatically unlocked on desktop session start using the password provided on login. For protecting it by a different password, you can set the password at the first use.

The Passwords and Keys application helps to manage the stored password and GNOME Keyring. It allows removing individual records or changing passwords.

Additional resources

  • For more information on Passwords and Keys, see the help manual for Passwords and Keys embedded directly in the desktop.

9.11. Accessing GVFS mounts that require authentication

This procedure describes how you can access GVFS mounts using authentication.

Procedure

  1. Open Files
  2. Activate the address bar by pressing Ctrl+L
  3. Enter a well-formed URI string of a service that needs authentication (for example, sftp://localhost/).

    The credentials dialog appears asking for a user name, password, and password storage options.

  4. Fill in the credentials and confirm.

9.12. GVFS back ends

Back ends in GVFS provide access to a specific type of resource. The following is a list of available GVFS back ends and their specifications:

Note

Some back ends are packaged separately and not installed by default. For installing additional back ends, use the yum package manager.

Table 9.1. Available back ends

Back endDescription

afc

Similar to MTP (Media Transfer Protocol), exposes files on your Apple iDevice (connected through USB).

afp

Apple Filing Protocol (AFP) client to access file services of macOS X and original Mac operation system.

archive

Handles various archiving files (ZIP, TAR) in read-only way.

admin

Provides admin access to the local file system.

burn

A virtual back end that burning applications use as a temporary storage for new CD, DVD, or BD medium contents.

cdda

Exposes Audio CD through separate Waveform Audio File Format (WAV) files.

computer

Virtual back end consolidating active mounts and physical volumes. Acts similarly to a signpost. Previously used by Nautilus for its Computer view.

dav, davs

WebDAV client, including secure variant. Authentication is possible only during mount. The back end does not support later re-authentication on per-folder basis.

dns-sd

DNS Service Discovery – Avahi client, used during network browsing, forms persistent URIs to discovered services.

ftp

A fully featured File Transfer Protocol (FTP) client. Supports passive transfers by default. Also, handles secure mode over ftps (explicit mode) and ftpis (implicit mode) schemes.

gphoto2

A Picture Transfer Protocol (PTP) client to access your camera attached by USB or FireWire.

google

Provides access to Google Drive. The Google Drive account needs to be configured over Gnome online accounts.

http

Handles all HTTP requests; useful for easy downloading files from web in client applications.

locatest

Simple testing back end that proxies the file:/// URI. The back end supports error injection.

mtp

Media Transfer Protocol back end for accessing media player and smart phone memory.

network

Allows you to browse Window Network and show shares discovered over Avahi.

recent

A back end used in the file chooser dialog to list recent files used by GNOME applications.

sftp

A fully-featured SSH File Transfer Protocol (SFTP) client.

smb

Access Samba and Windows shares.

trash

A trash back end which allows to restore deleted files.

9.13. Troubleshooting volume management in GNOME

Following are some common errors of volume management in GNOME and ways to resolve them.

9.13.1. Troubleshooting access to GVFS locations from non-GIO clients

If you have problems accessing GVFS locations from your application, it might mean that it is not native GIO client. Native GIO clients are typically all GNOME applications using GNOME libraries (glib, gio). The gvfs-fuse service is provided as a fallback for non-GIO clients.

Prerequisite

  • You have gvfs-fuse package installed.

    $ dnf install gvfs-fuse

    Procedure

    1. Ensure that gvfs-fuse is running.

      $ ps ax | grep gvfsd-fuse

      Since gvfs-fuse runs automatically and it is not recommended to start it by yourself, try logging out and logging in, if gvfs-fuse is not running.

    2. Find the system user ID (UID) for the /run/user/UID/gvfs/ path by running the id command, the gvfsd-fuse daemon requires a path it is supposed to expose its services at, or, when the /run/user/UID/gvfs/ path is unavailable, gvfsd-fuse uses a .gvfs path in your home directory.

      $ id -u
    3. If gvfsd-fuse is still not running, start the gvfsd-fuse daemon:

      $ /usr/libexec/gvfsd-fuse -f /run/user/UID/gvfs

      Now, the FUSE mount is available, and you can manually browse for the path in your application.

    4. Find the GVFS mounts under the /run/user/UID/gvfs/ or .gvfs locations.

9.13.2. Troubleshooting an invisible connected USB disk

Under certain circumstances, when you connect a flash drive, the GNOME Desktop might not display it. If your flash drive is not visible in Files, but you can see it in Disks application, you can attempt to set the Show in user interface flag in Disks.

Procedure

  1. Open the Disks application.
  2. Go to the Additional partition option actions menu clicking the cogwheel icon and click Edit Mount Options…​
  3. Click Show in user interface and confirm by clicking OK.
  4. If the flash drive is still not visible, you can try to physically remove the drive and try connecting it again.

9.13.3. Troubleshooting unknown or unwanted partitions listed in Files

Sometimes, you might see unknown or unwanted partitions when you plug a disk in. For example, when you plug in a flash disk, it is automatically mounted and its volumes are shown in the sidebar. Some devices have a special partition with backups, or help files which you might not want to see each time you plug in the device.

Procedure

  1. Open the Disks application.
  2. Go to the Additional partition option actions menu clicking the cogwheel icon and click Edit Mount Options…​
  3. Uncheck Show in user interface.
  4. Confirm by clicking OK.

9.13.4. Troubleshooting if a connection to the remote GVFS file system is unavailable

There are number of situations in which the client is unexpectedly and unwillingly disconnected from a virtual file system or a remote disk mount and is not reconnected automatically. You might see the error messages in such situations. Several causes trigger such situations:

  • The connection is interrupted. For example, your laptop is disconnected from the Wi-Fi.
  • The user is inactive for some time and is disconnected by the server (idle timeout).
  • The computer is resumed from sleep mode.

Procedure

  1. Unmount file system.
  2. Mount it again.
  3. If the connection is getting disabled more often, check the settings in the Network panel in the GNOME Settings.

9.13.5. Troubleshooting a busy disk in GNOME

If you receive a notification about your disk being busy, determine the programs that are accessing the disk. Then, you can end the programs that are running. You can also use the System Monitor to kill the programs forcefully.

Prerequisites

  • You have iotop installed. You can install it by running as a root user:
# yum install iotop

Procedure

  1. Examine the list of open files.

    • Run the lsof command to get the list of open files.
    • If lsof is not available, run the ps ax command.
    • You can use the System Monitor application to display the running processes in a GUI.
  2. When you have determined the programs, end or kill them as follows:

    • On the command line, execute the kill command.
    • In the System Monitor, right-click the line with the program process name, and click End or Kill from the context menu.

Additional resources

  • The kill man page.