Copyright (C) 2009 to 2013 and 2015 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 pmount. It provides a means of
mounting devices with pmount 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), (iii) the user wants to be able to mount
filesystems on user demand which are not removable media, such as
network filesystems, or (iv) the user just prefers pmount.

A separate 1.2 series of this program is now available which uses
udisks instead of pmount, for those who prefer PolicyKit for the
setting of mounting policy for block devices.  A 1.4 series is also
available which uses udisks2.  This 1.0 series of the program is
however still maintained.


                                USE

A graphical table of devices which may be mounted is provided by the
program.  These comprise the conventional device (eg /dev/hdc) and
label (eg cdrom) pair.  Normal pmount rules apply - the device will be
mounted in the /media directory on a mount point with the label name
which has been given unless the device appears in /etc/fstab, in which
case mounting will be handed off to the normal mount executable and
will be mounted at the point specified in /etc/fstab (in effect the
label will be ignored).  Network filesystems or FUSE filesystems may
be specified as a device in the mount-gtk table, but as they are not
block devices in /dev they must also be specified (and stated as user
mountable) in /etc/fstab - specifying the network address in
/etc/pmount.allow is neither necessary nor sufficient.  Where a
non-removable block device in /dev is to be mounted such as a second
internal hard disk, then the user must either specify it in /etc/fstab
or allow it to be mounted by pmount in /etc/pmount.allow.  These
normal overarching system policy rules are not overriden by mount-gtk.
See 'man pmount' for further details.

In summary:

  - removable block devices need no special attention and will be
    mounted by pmount in /media/[label] 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).

  - block devices which are not regarded by pmount as removable, such
    as SATA hard disks, must be whitelisted in /etc/pmount.allow for
    pmount to mount them.  Apart from this they behave as for
    removable disks

  - file systems which are not block devices having a device file in
    /dev, such as network file systems and FUSE file systems, cannot
    be mounted at a pmount label.  Instead they can be mounted by
    mount and therefore this program if the device and its mount point
    are specified in /etc/fstab.  Such file systems do not need to be
    whitelisted in /etc/pmount.allow in order to do so and are
    directly mounted using mount

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.


                             DEPENDENCIES

Dependences are:

pmount
glib >= 2.16.0
gtk+2 >= 2.12.0 or gtk+3 >= 2.99.0
c++-gtk-utils-1.2 >= 1.2.7, c++-gtk-utils-2.0 >= 2.0.0-rc1 or
  c++-gtk-utils-2.2 >= 2.1.0
dbus-glib >= 0.70 (not required if glib >= 2.26 is installed)

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

c++-gtk-utils-1.2 only requires C++98, whereas c++-gtk-utils-2.0
requires reasonably complete support for C++0x/11 at the level
provided by gcc-4.4 or later and c++-gtk-utils-2.2 requires gcc-4.6 or
later.  mount-gtk will compile with c++-gtk-utils-1.2,
c++-gtk-utils-2.0 or c++-gtk-utils-2.2, but if it is known that
C++0x/11 is supported to the level provided by gcc-4.4 or gcc-4.6,
then prefer c++-gtk-utils-2.0 or c++-gtk-utils-2.2 respectively; if
versions of gcc earlier than gcc-4.4 are also to be used to compile
this program, then use c++-gtk-utils-1.2.  c++-gtk-utils can be
obtained from http://cxx-gtk-utils.sourceforge.net/

All the versions of c++-gtk-utils will compile under GTK+2 and GTK+3.
To compile them for GTK+2, configure them with './configure-gtk2', and
to compile them 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.

Between glib-2.44 and glib-2.52, where linux is the operating system
/etc/mtab should be a link to /proc/mounts or /proc/self/mounts for
this program to work correctly.  This glib bug was fixed in glib-2.54
(prior to glib-2.44 and after glib-2.52, /etc/mtab can be a
self-standing file provided by mount).


                              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 any 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. The mount-gtk label is not used, and can be
something descriptive so that the entry can be recognised in the list
of mounts displayed by 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'.
