udiskie 1.3.2

Removable disk automounter for udisks

udiskie is a front-end for UDisks written in python. Its main purpose is automatically mounting removable media, such as CDs or flash drives. It has optional mount notifications, a GTK tray icon and user level CLIs for manual mount and unmount operations. The media will be mounted in a new directory under /media or /run/media/USER/, using the device name if possible.

Project pages

The source code is hosted on github.

Check out the wiki for installation instructions and general questions. Feel free to edit.

You can use the github issue tracker to report any issues you encounter, ask general questions or suggest new features.

There is also a public mailing list if you prefer email.

The latest release can be downloaded from PyPI.

Usage

Start the automount and notification daemon and show a system tray icon:

udiskie --tray

Mount or unlock a specific device manually:

udiskie-mount /dev/sdb1

Unmount or remove a specific device manually:

udiskie-umount /media/<device-name>
# or with udisks2
udiskie-umount -2 /run/media/<user>/<device>

See the man page for further instructions

Installation

0. benefit from others’ work

   • udiskie may be in your distribution’s official repositories

   • check out the wiki for guidance

   If neither of this helps, here are some general hints:

1. install dependencies:

   Required:

   • setuptools

   • PyGObject

   • UDisks (UDisks1 or UDisks2)

   • docopt (can automatically be installed by pip)

   Optional:

   • GTK3 (+introspection) for tray icon and password prompt. GTK2 also works if not using the tray icon.

   • libnotify (+introspection)

   • the notification daemon of your choice

   • gettext to build translation files (during setup step)

   • PyYAML for config file (can automatically be installed by pip)

   Access to system resources is mediated using PyGObject, which is why some packages need to be built with +introspection. Check the contents of the folder /usr/lib/girepository-1.0/ (or similar). There should be the following typelibs:

   • Gio-2.0

   • GLib-2.0

   • GObject-2.0

   • Gtk-3.0

   • Notify-0.7

   If you installed the above dependencies, but some of the typelibs are missing they might be distributed in separate packages. Note that the version numbers just indicate what udiskie is tested with, but it may work with other versions as well.

2. use pip to download and install udiskie itself:

   # from PyPI:
   pip install udiskie
   
   # from a local checkout:
   pip install .

3. go back to the wiki and edit. ;)

Permissions

udiskie requires permission for some polkit actions which are usually granted when using a desktop environment. If your login session is not properly activated you may need to customize your polkit settings. Create the file /etc/polkit-1/rules.d/50-udiskie.rules with the following contents:

polkit.addRule(function(action, subject) {
  var YES = polkit.Result.YES;
  // NOTE: there must be a comma at the end of each line except for the last:
  var permission = {
    // required for udisks1:
    "org.freedesktop.udisks.filesystem-mount": YES,
    "org.freedesktop.udisks.luks-unlock": YES,
    "org.freedesktop.udisks.drive-eject": YES,
    "org.freedesktop.udisks.drive-detach": YES,
    // required for udisks2:
    "org.freedesktop.udisks2.filesystem-mount": YES,
    "org.freedesktop.udisks2.encrypted-unlock": YES,
    "org.freedesktop.udisks2.eject-media": YES,
    "org.freedesktop.udisks2.power-off-drive": YES,
    // required for udisks2 if using udiskie from another seat (e.g. systemd):
    "org.freedesktop.udisks2.filesystem-mount-other-seat": YES,
    "org.freedesktop.udisks2.encrypted-unlock-other-seat": YES,
    "org.freedesktop.udisks2.eject-media-other-seat": YES,
    "org.freedesktop.udisks2.power-off-drive-other-seat": YES
  };
  if (subject.isInGroup("storage")) {
    return permission[action.id];
  }
});

This configuration allows all members of the storage group to run udiskie.

GTK icons

udiskie comes with a set of themeable custom Tango-style GTK icons for its tray icon menu. The installer tries to install the icons into GTK’s default hicolor theme. Typically this is located in /usr/share/icons/hicolor. If you have any problems with this or you need a custom path you can manually do it like so:

cp ./icons/scalable /usr/share/icons/hicolor -r
gtk-update-icon-cache /usr/share/icons/hicolor

When doing a local installation, for example in a virtualenv, you can manually change the installation prefix for the icon data files like so:

python setup.py install --install-data ~/.local

The icons roughly follow the Tango style guidelines. Some icons incorporate the CDROM icon of the base icon theme of the Tango desktop project (released into the public domain).

Contributing

udiskie is developed on github. Feel free to contribute patches as pull requests here.

Try to be consistent with the PEP8 guidelines. Add unit tests for all non-trivial functionality if possible. Dependency injection is a great pattern to keep modules flexible and testable.

Commits should be reversible, independent units if possible. Use descriptive titles and also add an explaining commit message unless the modification is trivial. See also: A Note About Git Commit Messages.

Further resources:

• UDisks1 API

• UDisks2 API

• PyGObject APIs

• Icon naming

• Icon lookup

CHANGELOG

1.3.2

• revert “respect the automount flag for devices”

• make dependency on Gtk optional

1.3.1

• use icon hints from udev settings in notifications

• respect the automount flag for devices

• don’t fail if libnotify is not available

1.3.0

• add actions to “Device added” notification

• allow to configure which actions should be added to notifications

1.2.1

• fix unicode issue in setup script

• update license/copyright notices

1.2.0

• use UDisks2 by default

• add –password-prompt command line argument and config file entry

1.1.3

• fix password prompt for GTK2 (tray is still broken for GTK2)

• fix minor documentation issues

1.1.2

• add key device_id for matching devices rather than only file systems

• improve documentation regarding dependencies

1.1.1

• fix careless error in man page

1.1.0

• implemented internationalization

• added spanish translation

• allow to choose icons from a configurable list

1.0.4

• compatibility with older version of pygobject (e.g. in Slackware 14.1)

1.0.3

• handle exception if no notification service is installed

1.0.2

• fix crash when calling udiskie mount/unmount utilites without udisks1 installed

1.0.1

• fix crash when calling udiskie without having udisks1 installed (regression)

1.0.0

• port to PyGObject, removing dependencies on pygtk, zenity, dbus-python, python-notify

• use a PyGObject based password dialog

• remove –password-prompt parameter

• rename command line parameters

• add negations for all command line parameters

0.8.0

• remove the ‘–filters’ parameter for good

• change config format to YAML

• change default config path to $XDG_CONFIG_HOME/udiskie/config.yml

• separate ignore filters from mount option filters

• allow to match multiple attributes against a device (AND-wise)

• allow to overwrite udiskies default handleability settings

• raise exception if –config file doesn’t exist

• add –options parameter for udiskie-mount

• simplify local installations

0.7.0

There are some backward incompatible changes, hence the version break:

• command line parameter ‘-f’/’–filters’ renamed to ‘-C’/’–config’

• add sections in config file to disable individual mount notifications and set defaults for some program options (udisks version, prompt, etc)

• refactor udiskie.cli, udiskie.config and udiskie.tray

• revert ‘make udiskie a namespace package’

• add ‘Browse folder’ action to tray menu

• add ‘Browse folder’ action button to mount notifications

• add ‘–no-automounter’ command line option to disable automounting

• add ‘–auto-tray’ command line option to use a tray icon that automatically disappears when no actions are available

• show notifications when devices dis-/appear (can be disabled via config file)

• show ‘id_label’ in tray menu, if available (instead of mount path or device path)

• add ‘Job failed’ notifications

• add ‘Retry’ button to failed notifications

• remove automatic retries to unlock LUKS partitions

• pass only device name to external password prompt

• add ‘–quiet’ command line option

• ignore devices ignored by udev rules

0.6.4

• fix logging in setup.py

• more verbose log messages (with time) when having -v on

• fix mounting devices that are added as ‘external’ and later changed to ‘internal’ [udisks1] (applies to LUKS devices that are opened by an udev rule for example)

0.6.3 (bug fix)

• fix exception in Mounter.detach_device if unable to detach

• fix force-detach for UDisks2 backend

• automatically use UDisks2 if UDisks1 is not available

• mount unlocked devices only once, removes error message on UDisks2

• mention __ignore__ in man page

0.6.2 (aesthetic)

• add custom icons for the context menu of the system tray widget

0.6.1 (bug fix)

• fix udisks2 external device detection bug: all devices were considered external when using Sniffer (as done in the udiskie-mount and udiskie-umount tools)

0.6.0 (udisks2 support, bug fix)

• cache device states to avoid some race conditions

• show filesystem label in mount/unmount notifications

• retry to unlock LUKS devices when wrong password was entered twice

• show ‘eject’ only if media is available (udisks1 ejects only in this case)

• (un-) mount/lock notifications shown even when operations failed

• refactor internal API

• experimental support for udisks2

0.5.3 (feature, bug fix)

• add ‘__ignore__’ config file option to prevent handling specific devices

• delay notifications until termination of long operations

0.5.2 (tray icon)

• add tray icon (pygtk based)

• eject / detach drives from command line

0.5.1 (mainly internal changes)

• use setuptools entry points to create the executables

• make udiskie a namespace package

0.5.0 (LUKS support)

• support for LUKS devices (using zenity for password prompt)

• major refactoring

• use setuptools as installer