Copyright (C) 2009 to 2013 Chris Vine

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    A copy of the GNU General Public License version 2 is set out below.
    You can also obtain a written copy from the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA


                              OVERVIEW

This program is a front end for udisks2 and mount. It provides a means
of mounting devices with udisks2 through a graphical interface.

It is principally intended for use where (i) the user does not want to
make use of the automounting facilities of say, nautilus, as and when
removable media are inserted in or removed from a computer, (ii) the
removable media are not recognised by nautilus (or whatever else is
used for automounting), or (iii) the user wants to be able to mount
filesystems on user demand which are not removable media, such as
network filesystems.

A separate 1.0 series of this program is available which uses pmount
instead of udisks2, for those who prefer pmount.  The 1.0 series is
still maintained.  A 1.2 series is also available which used udisks
(as opposed to udisks2) and is also still maintained.  The 1.0 and 1.2
series can also be compiled with older versions of gcc than this 1.4
series (they should compile with gcc-3.2 or above if c++-gtk-utils-1.2
is used).


                                USE

A graphical table of devices which may be mounted is provided by the
program.  This comprises the conventional device name (eg /dev/hdc)
together with a convenience identification label for each device.
Normal udisk rules apply - the device will be mounted in the /media
directory at a mount point derived from the mounted partition's label
name unless the device appears in /etc/fstab, in which case it will be
mounted at the point referred to in /etc/fstab.  Network filesystems
or FUSE filesystems may be specified as a device in the mount-gtk
table, because although they are not block devices mountable my
udisks, mount-gtk will hand off mounting to 'mount' (but as they are
not block devices in /dev they must also be specified in /etc/fstab).

If a block device is not stated in /etc/fstab, then whether the user
has permission to mount the device depends on PolicyKit permissions,
and in particular on the org.freedesktop.udisks2.filesystem-mount and
org.freedesktop.udisks2.filesystem-mount-system authorisations.  If
the device is stated in /etc/fstab, then whether the user has
permission to mount the device depends on the permissions given in
/etc/fstab.

Note that unlike pmount as used in the 1.0 series of this program, the
identification label supplied by the user in the table of devices in
the 1.2 and 1.4 series of this program is just a GUI identification
label for the convenience of the user.  This is a limitation in the
implementation of udisks.  However, unless the user selects otherwise
from the program preferences, if a device is mounted, its mount point
will be shown as a tooltip if the mouse is held over its mount button.

To mount a device at a user-chosen directory in /media, either the
relevant partition of the device to be mounted must be labelled with
the name in question, say using tune2fs, or the mount-point must be
specified in /etc/fstab.

In summary:

  - block devices need no special attention and will be mounted by
    udisks in the /media directory unless specified in /etc/fstab, in
    which case they will be mounted at the mount point specified in
    /etc/fstab (but to do so /etc/fstab must state them as 'user'
    mountable).

  - file systems which are not block devices having a device file in
    /dev, such as network file systems and FUSE file systems, must be
    specified in /etc/fstab in every case and stated as 'user'
    mountable.

The program is built as a single-instance program - if the user
attempts to start it when another instance of it is already running,
the existing instance will be brought up on the current desktop.  It
will therefore not usually be necessary to mark it as displayable on
all desktops - instead a normal program launcher for mount-gtk can be
placed in the desktop panel and clicked on when the user wants it
presented, or (if the tray icon option is chosen) the user can
left-click on the tray_icon to bring up an already running instance of
the program.

The program displays current mount state (if a mount button has a
green tag, then the device concerned is not mounted, and if it shows a
red tag it is already mounted).  Mount status is monitored using
glib's gio.

The program may be started with a -s option, which will start the
program hidden in the system tray.


                             DEPENDENCIES

Dependences are:

udisks2 >= 1.94.0
glib >= 2.26.0
gtk+2 >= 2.12.0 or gtk+3 >= 2.99.0
c++-gtk-utils-2.0 >= 2.0.9 or c++-gtk-utils-2.2 >= 2.1.0

A compiler supporting C++11 lambda expressions and range-for is
required, which means that if using gcc, gcc >= 4.6 is needed.

gtk+3 is supported.  See further under "GTK VERSIONS" for further
particulars about gtk+3.

c++-gtk-utils can be obtained from
http://cxx-gtk-utils.sourceforge.net/

c++-gtk-utils-2.0 and c++-gtk-utils-2.2 will compile under either
GTK+2 or GTK+3.  To compile for GTK+2, configure them with
'./configure-gtk2', and to compile for GTK+3, configure them with
'./configure-gtk3'.

It is also recommended, but not required, that libnotify >= 0.7.1 is
installed so that if there is a mounting error or some other problem,
an appropriate message can be displayed conveniently to the user.


                              GTK VERSIONS

The program can compile against GTK+3 as well as GTK+2.  Whichever one
of those has c++-gtk-utils compiled for it will be picked
automatically by the configure script.  If c++-gtk-utils has been
parallel installed for both GTK+2 and GTK+3, GTK+3 will be preferred,
but if mount-gtk is configured with the '--with-gtk-version=gtk2'
option, then the program will be configured and compiled against GTK+2
instead.  To compile against GTK+3, GTK+ >= 2.99.0 is required.

The mount-gtk configuration option '--with-gtk-version' can also be
given the values 'gtk3' and 'auto'.  If 'gtk3' is given, then
c++-gtk-utils must have been compiled and installed against GTK+3 if
configuration is to succeed; if 'auto' is given, then the effect is
the same as if the '--with-gtk-version' option had not been used.


                                 DBUS

The program operates as a single-instance program, and in order to do
so a dbus session message bus must be running.  Most recent
distributions using GNOME, KDE or Xfce do this anyway, but if your X
environment does not start a session bus, you may need to start one
yourself in the script which starts your X session.  To do this you
can put the following in the script (this will often be a xinitrc file
in /etc/X11/xinit, but might be ~/.xsession or ~/.Xclients):

  if test -z "$DBUS_SESSION_BUS_ADDRESS" ; then
    eval `dbus-launch --sh-syntax --exit-with-session`
    echo "D-Bus per-session daemon address is: $DBUS_SESSION_BUS_ADDRESS"
  fi

However, before amending your scripts, test whether this is necessary,
by trying to launch the program, or by bringing up a terminal (such as
xterm, gnome-terminal or konsole) and seeing if 'echo
$DBUS_SESSION_BUS_ADDRESS' reports anything.  (Usually it won't be
necessary to amend your scripts.)

If an attempt to start the program is made without the session message
bus running then an error dialog will be shown and the program will
then terminate.


                                 UDEV

With removable media, it is often convenient to give the media a
particular device name (say /dev/ipod instead of /dev/sdb2).  udev can
do this with an appropriate rule - see
http://reactivated.net/writing_udev_rules.html for information on how
to write udev rules.


                            FUSE FILESYSTEMS

mount-gtk can be used to mount and unmount FUSE filesystems, where the
mount point is specified in /etc/fstab.  It can thus mount and
unmount, for example, curlftpfs or sshfs.

Note that with sshfs, prompt-free login must be available, unless the
prompt is for a passphrase on an authentication key via a ssh
authentication tool with graphical interface, such as gnome-keyring or
the KDE graphical key authenticator.  This means that public/private
key authentication must be employed, and if there is a passphrase on
the key (as is recommended), either a graphical interface such as
gnome-keyring or the equivalent KDE tool must be employed, or the X
start-up script should start ssh-agent and export its environmental
variables (see 'man 1 ssh-agent') with ssh-add called before the
mounting of the ssh share is carried out (see 'man 1 ssh-add').

To unmount a FUSE file system with mount-gtk, the device name shown in
/etc/mtab when mounted must be the same as the device name in
/etc/fstab.  Not all FUSE filesystems do this, and in those cases it
is necessary to specify the device name to be given in /etc/mtab with
the FUSE 'fsname=' option.  This is the device name which must also be
specified in mount-gtk.

In the case of network file systems such as sshfs or curlftpfs, if the
network is lost the unmount may hang.  In such cases calling
fusermount -z on the relevant mount point by hand may help, or if not
it may be necessary to kill the file system process.

A typical /etc/fstab entry for sshfs might be:

sshfs#[username]@[address]:/home/[username]  /home/[username]/remote  fuse  reconnect,compression=yes,noauto,user,fsname=sshfs#[username]@[address]:/home/[username] 0 0

A typical /etc/fstab entry for curlftpfs might be:

curlftpfs#ftp://ftp.kernel.org/pub/linux/kernel  /mnt/kernel  fuse  allow_other,noauto,user,fsname=curlftpfs#ftp://ftp.kernel.org/pub/linux/kernel 0 0

A typical /etc/fstab entry for obexfs and bluetooth might be:

obexfs#-bXX:XX:XX:XX:XX:XX  /mnt/bluetooth  fuse  allow_other,noauto,user,fsname=obexfs#-bXX:XX:XX:XX:XX:XX 0 0

The 'allow_other' option will allow other users to access the mounted
share.  It is of no effect unless the line:

user_allow_other

appears in /etc/fuse.conf.  It would not generally be appropriate for
a home directory, as it would give all users access to the mounted
share with the identity and permissions of the logged in user.
Another possible option is 'allow_root'.
