Administering the system using the GNOME desktop environment

Red Hat Enterprise Linux 9

Administering Red Hat Enterprise Linux 9 using the GNOME desktop environment

Red Hat Customer Content Services

Abstract

This document describes how to perform selected system administration tasks using GNOME, which is the only available desktop environment in RHEL 9.

Preface

Important

To function properly, GNOME requires your system to support 3D acceleration. This includes bare metal systems, as well as hypervisor solutions such as VMWare.

If GNOME does not start or performs poorly on your VMWare virtual machine (VM), see the following solution: Why does the GUI fail to start on my VMware virtual machine?

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

Providing feedback on Red Hat documentation

We appreciate your feedback on our documentation. Let us know how we can improve it.

Submitting feedback through Jira (account required)

  1. Log in to the Jira website.
  2. Click Create in the top navigation bar
  3. Enter a descriptive title in the Summary field.
  4. Enter your suggestion for improvement in the Description field. Include links to the relevant parts of the documentation.
  5. Click Create at the bottom of the dialogue.

Chapter 1. Installing software in GNOME

You can install applications and other software packages using several methods in GNOME.

1.1. Prerequisites

  • You have administrator permissions on the system.

1.2. The GNOME Software application

GNOME Software is an utility that enables you to install and update applications and software components in a graphical interface.

GNOME Software provides a catalog of graphical applications, which are the applications that include a *.desktop file. The available applications are grouped into multiple categories according to their purpose.

GNOME Software uses the PackageKit and Flatpak technologies as its back ends.

1.3. Installing an application using GNOME Software

This procedure installs a graphical application using the GNOME Software utility.

Procedure

  1. Launch the GNOME Software application.
  2. Find the application that you want to install using any of the following methods:

    • Click the search button (🔍) in the upper-left corner of the window and type the name of the application.

      Application search in GNOME Software

    • Browse the application categories in the Explore tab.

      Explore screen in GNOME Software

  3. Click the selected application.
  4. Click Install.

    Install LibreOffice Writer

1.4. Installing an application to open a file type

This procedure installs an application that can open a given file type.

Prerequisites

  • You can access a file of the required file type in your file system.

Procedure

  1. Try opening a file that is associated with an application that is currently not installed on your system.
  2. GNOME automatically identifies the suitable application that can open the file, and offers to download the application.

1.5. Installing an RPM package file in GNOME

This procedure installs an RPM software package that you manually downloaded as a file.

Prerequisites

  • You have downloaded the required RPM package.

Procedure

  1. In the Files application, open the directory that stores the downloaded RPM package.

    Note

    By default, downloaded files are stored in the /home/user/Downloads/ directory.

  2. Double-click the RPM package file to install it.

1.6. Installing an application from the Activities Overview search

This procedure installs a graphical application from search results on the GNOME Activities Overview screen.

Procedure

  1. Open the Activities Overview screen.
  2. Type the name of the required application in the search entry.

    LibreOffice Writer in the search results

    The search results display the application’s icon, name, and description.

  3. Click the application’s icon to open the Software application.

    LibreOffice Writer in Software

  4. Click Install to finish the installation in Software.

Verification

  • Click Open to launch the installed application.

1.7. Additional resources

Chapter 2. Installing applications using Flatpak

You can install certain applications using the Flatpak package manager. The following sections describe how to search for, install, launch, and update Flatpak applications on the command line and in the graphical interface.

Important

Red Hat provides Flatpak applications only as a Technology Preview feature. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview.

The Flatpak package manager itself is fully supported.

2.1. The Flatpak technology

Flatpak provides a sandbox environment for application building, deployment, distribution, and installation.

Applications that you launch using Flatpak have minimum access to the host system, which protects the system installation against third-party applications. Flatpak provides application stability regardless of the versions of libraries installed on the host system.

Flatpak applications are distributed from repositories called remotes. Red Hat provides a remote with RHEL applications. Additionally, third-party remotes are available as well. Red Hat does not support applications from third-party remotes.

2.2. Setting up Flatpak

This procedure installs the Flatpak package manager.

Procedure

  • Install the flatpak package:

    # dnf install flatpak

2.3. Enabling the Red Hat Flatpak remote

This procedure configures the Red Hat Container Catalog as a Flatpak remote on your system.

Prerequisites

  • You have an account on the Red Hat Customer Portal.

    Note

    For large-scale deployments where the users do not have Customer Portal accounts, Red Hat recommends using registry service accounts. For details, see Registry Service Accounts.

Procedure

  1. Enable the rhel Flatpak remote:

    $ flatpak remote-add \
              --if-not-exists \
              rhel \
              https://flatpaks.redhat.io/rhel.flatpakrepo
  2. Log into the Red Hat Container Catalog:

    $ podman login registry.redhat.io
    
    Username: your-user-name
    Password: your-password

    Provide the credentials to your Red Hat Customer Portal account or your registry service account tokens.

    By default, Podman saves the credentials only until you log out.

  3. Optional: Save your credentials permanently. Use one of the following options:

    • Save the credentials for the current user:

      $ cp $XDG_RUNTIME_DIR/containers/auth.json \
           $HOME/.config/flatpak/oci-auth.json
    • Save the credentials system-wide:

      # cp $XDG_RUNTIME_DIR/containers/auth.json \
           /etc/flatpak/oci-auth.json

      For best practices, Red Hat recommends that you log into the Red Hat Container Catalog using registry account tokens when installing credentials system-wide.

Verification

  • List the enabled Flatpak remotes:

    $ flatpak remotes
    
    Name    Options
    rhel    system,oci,no-gpg-verify

2.4. Searching for Flatpak applications

This procedure searches for an application in the enabled Flatpak remotes on the command line. The search uses the application name and description.

Prerequisites

  • Flatpak is installed.
  • The Red Hat Flatpak repository is enabled.

Procedure

  • Search for an application by name:

    $ flatpak search application-name

    For example, to search for the LibreOffice application, use:

    $ flatpak search LibreOffice

    The search results include the ID of the application:

    Application ID               Version  Branch  Remotes  Description
    
    org.libreoffice.LibreOffice           stable  rhel     The LibreOffice productivity suite

2.5. Installing Flatpak applications

This procedure installs a selected application from the enabled Flatpak remotes on the command line.

Prerequisites

  • Flatpak is installed.
  • The Red Hat Flatpak remote is enabled.

Procedure

  • Install an application from the rhel remote:

    $ flatpak install rhel application-id

    Replace application-id with the ID of the application. For example:

    $ flatpak install rhel org.libreoffice.LibreOffice

2.6. Launching Flatpak applications

This procedure launches an installed Flatpak application from the command line.

Prerequisites

  • Flatpak is installed.
  • The selected Flatpak application is installed.

Procedure

  • Launch the application:

    $ flatpak run application-id

    Replace application-id with the ID of the application. For example:

    $ flatpak run org.libreoffice.LibreOffice

2.7. Updating Flatpak applications

This procedure updates one or more installed Flatpak applications to the most recent version in the corresponding Flatpak remote.

Prerequisites

  • Flatpak is installed.
  • A Flatpak remote is enabled.

Procedure

  • Update one or more Flatpak applications:

    • To update a specific Flatpak application, specify the application ID:

      $ flatpak update application-id
    • To update all Flatpak applications, specify no application ID:

      $ flatpak update

2.8. Installing Flatpak applications in the graphical interface

This procedure searches for Flatpak applications using the Software application.

Prerequisites

  • Flatpak is installed.
  • The Red Hat Flatpak remote is enabled.

Procedure

  1. Open the Software application.
  2. Make sure that the Explore tab is active.
  3. Click the search button in the upper-left corner of the window.
  4. In the input box, type the name of the application that you want to install, such as LibreOffice.
  5. Select the correct application in the search results.

    If the application is listed several times, select the version where the Source field in the Details section reports flatpaks.redhat.io.

  6. Click the Install button.
  7. If Software asks you to log in, enter your Customer Portal credentials or your registry service account tokens.
  8. Wait for the installation process to complete.
  9. Optional: Click the Launch button to launch the application.

2.9. Updating Flatpak applications in the graphical interface

This procedure updates one or more installed Flatpak applications using the Software application.

Prerequisites

  • Flatpak is installed.
  • A Flatpak remote is enabled.

Procedure

  1. Open the Software application.
  2. Select the Updates tab.
  3. In the Application Updates section, you can find all available updates to Flatpak applications.
  4. Update one or more applications:

    • To apply all available updates, click the Update All button.
    • To update only a specific application, click the Update button next to the application item.
  5. Optional: Enable automatic application updates.

    1. Click the menu button in the upper-right corner of the window.
    2. Select Update Preferences.
    3. Enable Automatic Updates.

      Flatpak applications now update automatically.

Chapter 3. Registering the system for updates using GNOME

You must register your system to get software updates for your system. This section explains how you can register your system using GNOME.

Prerequisites

  • A valid account with Red Hat customer portal

    See the Create a Red Hat Login page for new user registration.

  • Activation Key or keys, if you are registering the system with activation key
  • A registration server, if you are registering system using the registration server

3.1. Registering a system using Red Hat account on GNOME

Follow the steps in this procedure to enroll your system with your Red Hat account.

Prerequisites

Procedure

  1. Open the system menu, which is accessible from the upper-right screen corner, and click Settings.

    System menu

  2. Go to AboutSubscription.
  3. If you are not using the Red Hat server:

    1. In the Registration Server section, select Custom Address.
    2. Enter the server address in the URL field.
  4. In the Registration Type section, select Red Hat Account.
  5. In the Registration Details section:

    • Enter your Red Hat account user name in the Login field.
    • Enter your Red Hat account password in the Password field.
    • Enter the name of your organization in the Organization field.
  6. Click Register.

3.2. Registering a system using an activation key on GNOME

Follow the steps in this procedure to register your system with an activation key. You can get the activation key from your organization administrator.

Prerequisites

  • Activation key or keys.

    See the Activation Keys page for creating new activation keys.

Procedure

  1. Open the system menu, which is accessible from the upper-right screen corner, and click Settings.

    System menu

  2. Go to AboutSubscription.
  3. If you are not using the Red Hat server:

    1. In the Registration Server section, select Custom Address.
    2. Enter the server address in the URL field.
  4. In the Registration Type section, select Activation Keys.
  5. Under Registration Details:

    • Enter your activation keys in the Activation Keys field.

      Separate your keys by a comma (,).

    • Enter the name or ID of your organization in the Organization field.
  6. Click Register.

3.3. Unregistering the system using GNOME

Follow the steps in this procedure to unregister your system. After unregistering, your system no longer receives software updates.

Procedure

  1. Open the system menu, which is accessible from the upper-right screen corner, and click Settings.

    System menu

  2. Go to AboutSubscription.

    The Registration Details screen appears.

  3. Click Unregister.

    A warning appears about the impact of unregistering the system.

  4. Click Unregister.

3.4. Additional resources

Chapter 4. Changing the language using desktop GUI

This section describes how to change the system language using the desktop GUI.

Prerequisites

  • Required language packages are installed on your system

Procedure

  1. Open the Settings application from the system menu by clicking on its icon.

    cs system menu9

  2. In Settings, choose Region & Language from the left side bar.
  3. Click the Language menu.

    cs language menu9

  4. Select the required region and language from the menu.

    cs select region language9

    If your region and language are not listed, scroll down, and click More to select from available regions and languages.

    cs available region language9

  5. Click Done.
  6. Click Restart for changes to take effect.

    cs restart region language9

Note

Some applications do not support certain languages. The text of an application that cannot be translated into the selected language remains in US English.

Additional resources

Chapter 5. Changing how your system behaves when you close the laptop lid

When you close the lid of your laptop, it suspends by default to save battery. You can customize this behavior according to your preferences.

WARNING
Some laptops can overheat if they are left running with the lid closed, especially in confined spaces. Consider whether changing this setting is safe for your laptop, especially if you intend to keep the laptop running with the lid closed for extended periods of time.

Prerequisites

  • Administrative access.

Procedure

  1. Open the /etc/systemd/logind.conf configuration file.
  2. Look for the line that says HandleLidSwitch=suspend.
  3. If the line starts with the # symbol, remove it to enable the setting.
  4. Replace suspend with one of the following options:

    • poweroff to shut down the computer.
    • lock to lock the screen.
    • ignore to do nothing.

    For example, to lock the screen upon closing the lid, use this setting:

    HandleLidSwitch=lock
  5. Save your changes and close the editor.

Chapter 6. Changing how your system behaves when you press the power button

When you press the power button on your computer, it shuts down the system by default. You can customize this behavior according to your preferences.

Prerequisites

  • Administrative access.

Procedure

  1. Open the /etc/systemd/logind.conf configuration file.
  2. Look for the line that says HandlePowerKey=poweroff.
  3. If the line starts with the # symbol, remove it to enable the setting.
  4. Replace poweroff with one of the following options:

    • poweroff to shut down the computer.
    • reboot for a system reboot.
    • halt to initiate a system halt.
    • kexec for a kexec-based reboot.
    • suspend to suspend the system.
    • hibernate to initiate system hibernation.
    • ignore to do nothing.

    For example, to reboot the system upon pressing the power button, use this setting:

    HandlePowerKey=reboot
  5. Save your changes and close the editor.

Chapter 7. Displaying the system security classification

As an administrator of deployments where the user must be aware of the security classification of the system, you can set up a notification of the security classification. This can be either a permanent banner or a temporary notification, and it can appear on login screen, in the GNOME session, and on the lock screen.

7.1. Enabling system security classification banners

You can create a permanent classification banner to state the overall security classification level of the system. This is useful for deployments where the user must always be aware of the security classification level of the system that they are logged into.

The permanent classification banner can appear within the running session, the lock screen, and login screen, and customize its background color, its font, and its position within the screen.

This procedure creates a red banner with a white text placed on both the top and bottom of the login screen.

Procedure

  1. Install the gnome-shell-extension-classification-banner package:

    # dnf install gnome-shell-extension-classification-banner
  2. Create the 99-class-banner file at either of the following locations:

    • To configure a notification at the login screen, create /etc/dconf/db/gdm.d/99-class-banner.
    • To configure a notification in the user session, create /etc/dconf/db/local.d/99-class-banner.
  3. Enter the following configuration in the created file:

    [org/gnome/shell]
    enabled-extensions=['classification-banner@gnome-shell-extensions.gcampax.github.com']
    
    [org/gnome/shell/extensions/classification-banner]
    background-color='rgba(200,16,46,0.75)'
    message='TOP SECRET'
    top-banner=true
    bottom-banner=true
    system-info=true
    color='rgb(255,255,255)'
    Warning

    This configuration overrides similar configuration files that also enable an extension, such as Notifying of the system security classification.

    To enable multiple extensions, specify all of them in the enabled-extensions list. For example:

    enabled-extensions=['heads-up-display@gnome-shell-extensions.gcampax.github.com', 'classification-banner@gnome-shell-extensions.gcampax.github.com']
  4. Update the dconf database:

    # dconf update
  5. Reboot the system.

Troubleshooting

  • If the classification banners are not displayed for an existing user, log in as the user and enable the Classification banner extension using the Extensions application.

7.2. Notifying of the system security classification

You can set up a notification that contains a predefined message in an overlay banner. This is useful for deployments where the user is required to read the security classification of the system before logging in.

Depending on your configuration, the notification can appear at the login screen, after logging in, on the lock screen, or after a longer time with no user activity. You can always dismiss the notification when it appears.

Procedure

  1. Install the gnome-shell-extension-heads-up-display package:

    # dnf install gnome-shell-extension-heads-up-display
  2. Create the 99-hud-message file at either of the following locations:

    • To configure a notification at the login screen, create /etc/dconf/db/gdm.d/99-hud-message.
    • To configure a notification in the user session, create /etc/dconf/db/local.d/99-hud-message.
  3. Enter the following configuration in the created file:

    [org/gnome/shell]
    enabled-extensions=['heads-up-display@gnome-shell-extensions.gcampax.github.com']
    
    [org/gnome/shell/extensions/heads-up-display]
    message-heading="Security classification title"
    message-body="Security classification description"
    # The following options control when the notification appears:
    show-when-locked=true
    show-when-unlocking=true
    show-when-unlocked=true

    Replace the following values with text that describes the security classification of your system:

    Security classification title
    A short heading that identifies the security classification.
    Security classification description
    A longer message that provides additional details, such as references to various guidelines.
    Warning

    This configuration overrides similar configuration files that also enable an extension, such as Enabling system security classification banners.

    To enable multiple extensions, specify all of them in the enabled-extensions list. For example:

    enabled-extensions=['heads-up-display@gnome-shell-extensions.gcampax.github.com', 'classification-banner@gnome-shell-extensions.gcampax.github.com']
  4. Update the dconf database:

    # dconf update
  5. Reboot the system.

Troubleshooting

  • If the notifications are not displayed for an existing user, log in as the user and enable the Heads-up display message extension using the Extensions application.

Chapter 8. Setting a default desktop session for all users

You can configure a default desktop session that is preselected for all users that have not logged in yet.

If a user logs in using a different session than the default, their selection persists to their next login.

Procedure

  1. Copy the configuration file template:

    # cp /usr/share/accountsservice/user-templates/standard \
         /etc/accountsservice/user-templates/standard
  2. Edit the new /etc/accountsservice/user-templates/standard file. On the Session=gnome line, replace gnome with the session that you want to set as the default.
  3. Optional: To configure an exception to the default session for a certain user, follow these steps:

    1. Copy the template file to /var/lib/AccountsService/users/user-name:

      # cp /usr/share/accountsservice/user-templates/standard \
           /var/lib/AccountsService/users/user-name
    2. In the new file, replace variables such as ${USER} and ${ID} with the user values.
    3. Edit the Session value.

Chapter 9. Setting up a printer

In GNOME, you can set up printing using the Settings application.

9.1. Accessing printer settings in GNOME

Procedure

  1. Use one of the approaches described in Launching applications to start the Settings application.

    Moreover, you can also start the Settings application from the system menu in the upper right corner by clicking on the "Settings" icon.

    System menu

  2. When the Settings application GUI appears, go to Printers.

    Figure 9.1. GNOME Control center configuration tool

    gnome control center add printer 9

9.2. Adding a new printer in Settings

You can add a new printer using the Settings application.

Prerequisites

  • Click the Unlock button, which appears near the upper-right corner of the Printers screen, and authenticate as one of the following users:

    • Superuser
    • Any user with the administrative access provided by sudo (users listed within /etc/sudoers)
    • Any user belonging to the printadmin group in /etc/group

Procedure

  1. Open the Printers dialog.

    gnome control center add printer 9
  2. Click on Unlock and authenticate.

    add printer gcc unlock authenticate 9
  3. Select one of the available printers (including also network printers), or enter printer IP address or the host name of a printer server.

    gnome control center select printer 9
    gnome control center add network printer 9
  4. Confirm your selection by clicking Add in the top right corner.

    gnome control center add network printer confirm 9

9.3. Printing a test page in Settings

You can print a test page to make sure that the printer functions properly.

Prerequisites

  • A printer has been set up.

Procedure

  1. Click the settings (⚙️) button on the right to display a settings menu for the selected printer:

    gnome control center printer settings 9
  2. Click Printing OptionsTest Page.

Chapter 10. Modifying printer settings

In GNOME, you can modify printer settings using the Settings application.

Prerequisites

10.1. Displaying and modifying printer’s details

To maintain a configuration of a printer, use the Settings application:

Procedure

  1. Click the settings (⚙️) button on the right to display a settings menu for the selected printer:

    gnome control center printer settings 9
  2. Click Printer Details to display and modify selected printer’s settings:

    gnome control center printer details 9

    In this menu, you can select the following actions:

    Search for Drivers
    GNOME Control Center communicates with PackageKit that searches for a suitable driver suitable in available repositories.
    Select from Database
    This option enables you to select a suitable driver from databases that have already been installed on the system.
    Install PPD File
    This option enables you to select from a list of available postscript printer description (PPD) files that can be used as a driver for your printer.
    gnome control center printer details more 9

10.2. Setting the default printer

You can set the selected printer as the default printer.

Procedure

  1. Click the settings (⚙️) button on the right to display a settings menu for the selected printer:

    gnome control center printer settings 9
  2. Click Use Printer by Default to set the selected printer as the default printer:

    gnome control center default printer 9

10.3. Setting printing options

Procedure

  1. Click the settings (⚙️) button on the right to display a settings menu for the selected printer:

    gnome control center printer settings 9
  2. Click Printing Options.

10.4. Removing a printer

You can remove a printer using the Settings application.

Procedure

  1. Click the settings (⚙️) button on the right to display a settings menu for the selected printer:

    gnome control center printer settings 9
  2. Click Remove Printer to remove the selected printer:

    gnome control center remove printer 9

Chapter 11. Browsing files on a network share

You can connect to a network share provided by a server and browse the files on the server like local files. You can download or upload files using the file browser.

11.1. GVFS URI format for network shares

GNOME uses the GVFS URI format to refer to network shares and files on them. When you connect to a network share from GNOME, you provide the address to the network share in the following format.

A URL, or uniform resource locator, is a form of address that refers to a location or file on a network. The address is formatted like this:

The basic GVFS URI format takes the following syntax:

protocol://server.example.com/folder/file

The scheme specifies the protocol or type of server. The example.com portion of the address is called the domain name. If a username is required, it is inserted before the server name:

You can also specify the user name or the port number to the network share:

protocol://user@server.example.com:port/folder/file

Table 11.1. Common network share protocols

ProtocolGVFS URI example

SSH

ssh://user@server.example.com/path

NFS

nfs://server/path

Windows SMB

smb://server/Share

WebDAV

dav://example.server.com/path

Public FTP

ftp://ftp.example.com/path

Authenticated FTP

ftp://user@ftp.example.com/path

11.2. Mounting a storage volume in GNOME

You can manually mount a local storage volume or a network share in the Files application.

Procedure

  1. Open the Files application.
  2. Click Other Locations in the side bar.

    The window lists all connected storage volumes and all network shares that are publicly available on your local area network.

    If you can see the volume or network share in this list, mount it by clicking the item.

    If you want to connect to a different network share, use the following steps.

  3. Enter the GVFS URI string to the network share in the Connect to Server field.
  4. Press Connect.
  5. If the dialog asks you for login credentials, enter your name and password into the relevant fields.
  6. When the mounting process finishes, you can browse the files on the volume or network share.

11.3. Unmounting a storage volume in GNOME

You can unmount a storage volume, a network share, or another resource in the Files application.

Procedure

  1. Open the Files application.
  2. In the side bar, click the Unmount (⏏) icon next to the chosen mount.
  3. Wait until the mount disappears from the side bar or a notification about the safe removal appears.

11.4. Additional resources (or Next steps)

Chapter 12. 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.

12.1. The GVFS system

GVFS provides complete virtual file system infrastructure and handles storage in the GNOME desktop. It uses addresses for full identification based on the Uniform Resource Identifier (URI) 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.

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, the mount 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.

12.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, which points to a root directory (/) of the File Transfer Protocol (FTP) server running at the ftp.myserver.net domain:

Example 12.1. A URI string pointing to the root FTP directory

ftp://ftp.myserver.net/

Example 12.2. A URI string pointing to a text file on FTP

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

12.3. Mounting a storage volume in GNOME

You can manually mount a local storage volume or a network share in the Files application.

Procedure

  1. Open the Files application.
  2. Click Other Locations in the side bar.

    The window lists all connected storage volumes and all network shares that are publicly available on your local area network.

    If you can see the volume or network share in this list, mount it by clicking the item.

    If you want to connect to a different network share, use the following steps.

  3. Enter the GVFS URI string to the network share in the Connect to Server field.
  4. Press Connect.
  5. If the dialog asks you for login credentials, enter your name and password into the relevant fields.
  6. When the mounting process finishes, you can browse the files on the volume or network share.

12.4. Unmounting a storage volume in GNOME

You can unmount a storage volume, a network share, or another resource in the Files application.

Procedure

  1. Open the Files application.
  2. In the side bar, click the Unmount (⏏) icon next to the chosen mount.
  3. Wait until the mount disappears from the side bar or a notification about the safe removal appears.

12.5. Access to GVFS mounts in the file system

Learn more about FUSE, the main daemon for the GVFS virtual file system.

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 main gvfs daemon and mounts volumes either in the /run/user/UID/gvfs/ or ~/.gvfs/ directories 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.

12.6. Available GIO commands

GIO provides several commands that might be useful for scripting or testing.

Here is a set of POSIX commands counterparts as follows:

CommandDescription

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:

CommandDescription

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.

Additional resources

  • The gio(1) man page.

12.7. Sample GIO commands

The following section provides a few examples of the GIO commands usage.

Example 12.3. List all files in the local /tmp directory

$ gio list file:///tmp

Example 12.4. List the content of a text file from a remote system

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

Example 12.5. Copy the previous text file to a local /tmp directory

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

Additional resources

  • The gio man page.

12.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.

12.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.

12.10. Password management of GVFS mounts

Learn more about the GVFS mount authentication.

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 whether 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.

12.11. GVFS back ends

Back ends in GVFS provide access to a specific type of resource. This section provides 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 dnf package manager.

Table 12.1. Available back ends

Back endDescription

admin

Provides administrator 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 content.

cdda

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

computer

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

dav, davs

A 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: An 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 in the Online Accounts settings.

http

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

locatest

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

mtp

A Media Transfer Protocol (MTP) 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

Accesses Samba and Windows shares.

trash

A trash back end that allows to restore deleted files.

Chapter 13. Troubleshooting volume management in GNOME

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

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

  • The gvfs-fuse package is installed.

    $ dnf install gvfs-fuse

Procedure

  1. Ensure that gvfs-fuse is running.

    $ ps ax | grep gvfsd-fuse

    If gvfs-fuse is not running, log out and log back in. Red Hat does not recommend starting gvfs-fuse manually.

  2. Find the system user ID (UID) for the /run/user/UID/gvfs/ path.

    The gvfsd-fuse daemon requires a path where it can expose its services. When the /run/user/UID/gvfs/ path is unavailable, gvfsd-fuse uses the ~/.gvfs path.

    $ 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.

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 the Disks application, you can attempt to set the Show in user interface option in Disks.

Procedure

  1. Open the Disks application.
  2. Select the disk in the side bar.
  3. Below Volumes, Click Additional partition options (⚙)Edit Mount Options…​.
  4. Click Show in user interface.
  5. Confirm by clicking OK.
  6. If the flash drive is still not visible, you can try to physically remove the drive and try connecting it again.

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 Files side bar. 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. Select the disk in the side bar.
  3. Below Volumes, Click Additional partition options (⚙)Edit Mount Options…​.
  4. Uncheck Show in user interface.
  5. Confirm by clicking OK.

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.

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 application to kill the programs forcefully.

Prerequisites

  • The iotop utility is installed:

    # dnf 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 System Monitor to display the running processes in a GUI.
  2. When you have determined the programs, terminate them using any of the following methods:

    • On the command line, execute the kill command.
    • In 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.

Chapter 14. Storing user settings over NFS

If you use GNOME on a system with NFS home directories, you must set the keyfile back end for the dconf database. Otherwise, dconf might not work correctly. With this configuration, dconf stores settings in the ~/.config/dconf-keyfile/user file.

Procedure

  1. Create or edit the /etc/dconf/profile/user file on every client.
  2. At the very beginning of the /etc/dconf/profile/user file, add the following line:

    service-db:keyfile/user
  3. Users must log out and log back in.

    dconf polls the keyfile back end to determine whether updates have been made, so settings might not be updated immediately.

Legal Notice

Copyright © 2024 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.