GMailFS HOWTO: Guide to Using Your GMail Account as a Linux File System
last updated: 10/26/2006
Auther: Aaron Miller (armantic101@gmail.com)
I will try to keep this document as current as possible, however the official (and most up to date) version can be found at
http://www.drkstr.org/HOWTO-GMailFS.html
Contents
1.0 Overview
2.0 Install Needed Software
2.1 Install FUSE
2.2 Install Python FUSE Bindings
2.3 Install LibGMail
2.4 Install GMailFS
3.0 Using Your GMail File System
3.1 Configure GMailFS
3.2 Mount GMail file system
4.0 Fine Tuning
4.1 Auto Archive GMailFS Messages to Prevent Inbox Clutter
4.2 Modify GMailFS to Display True File Name for EMail Attachment
5.0 Change Log
1.0 Overview
This is a quick guide to using your GMail account as a Linux file system, via GMailFS by Richard Jones. This might be useful to back up files or give your self access to your saved files from anywhere that has a web browser.
The GMailFS file system
The file system is created by posting email messages to your account that contain references to the inode, directory structure, and other file system information in the subject and email header. Actual files are saved as an attachment and files over the max attachment size are broken into multiple attachments.
Extra Reading:
http://richard.jones.name/google-hac...ilesystem.html
http://fuse.sourceforge.net/
http://sourceforge.net/projects/libgmail
System Requirements:
GMail email account
Linux Kernel 2.4 or later
Python 2.3 or later
FUSE - implements userspace file systems in Linux
FUSE Python Bindings - needed for file system code written in python
LibGMail - libraries for GMail access and message handling
GMailFS - the libraries for the GMail file system
2.0 Install Needed Software
2.1 Install FUSE
First we must enable functionality for Userspace Files Systems which are supported in Linux through the FUSE project.
For Kernels >= 2.6.14, you should enable kernel support by adding the fuse.ko module. For earlier kernels, FUSE will build the appropriate kernel module for you.
In your kernel config menu, find the following option and enable it as a module.
FileSystems->
<M>Filesystem in Userspace support
then compile and install the module with:
Code:
make modules && make modules_install
See the
Kernel-HOWTO.html for more information on compiling the Linux kernel.
We will next need to download the FUSE tarball from:
http://fuse.sourceforge.net/
and extract with
Code:
tar -vxf fuse-2.5.3.tar.gz
Then build with
Code:
./configure --prefix=/usr
make
make install
note: Make sure the --prefix points to where all your system libraries will be installed. Also, './configure' will not build the kernel module if it all ready detected on your system. Make sure it detects/does not detect, correctly.
Once FUSE is installed correctly run:
Code:
modprobe fuse
ldconfig
ldconfig might be needed to update the library linker.
2.2 Install Python FUSE Bindings
You will need to install the Python FUSE bindings to get the Python FUSE libraries.
To download the correct bindings, issue the following commands in the directory you want to download them to.
Code:
cvs -d:pserver:anonymous@fuse.cvs.sourceforge.net:/cvsroot/fuse login
cvs -z3 -d:pserver:anonymous@fuse.cvs.sourceforge.net:/cvsroot/fuse co -P python
Just hit 'enter' at the password prompt.
Then from the root of the directory you just checked out from CVS:
Code:
python setup.py build
python setup.py install
Make sure to take note of where the install routine copied the build files. It will display at the end of the output from install. On my system it installed to '/usr/lib/python2.4/site-packages/' This is a shared directory python uses for libraries and dependencies.
2.3 Install LibGMail
Now to install LibGMail which is a library for reading/writing GMail messages and handles the connection process. You can download from:
http://sourceforge.net/projects/libgmail
and then extract with the same method as above. Once extracted, cd to the extracted directory and copy lgconstants.py & libgmail.py to same directory the FUSE python bindings were installed to earlier.
Code:
cp lgconstants.py /usr/lib/python2.4/site-packages/
cp libgmail.py /usr/lib/python2.4/site-packages/
2.4 Install GMailFS
Now for the meat and potatoes. Download GMailFS from:
http://richard.jones.name/google-hac...ilesystem.html
and extract as before. Cd to the extracted directory and copy the following files to their correct location:
Code:
cp gmailfs.py /usr/bin/
cp mount.gmailfs /sbin/
cp gmailfs.conf /etc/
Assuming everything installed correctly, we should now be ready to use our GMail account as a Linux file system.
3.0 Using Your GMail File System
3.1 Configure GMailFS
First thing we should do is open the /etc/gmail.conf file in a text editor and update the following lines.
Code:
username=yourusername
password=yourpassword
fsname=yourfsname
The fsname should be equally complex and secretive as your password. If someone were to guess your file system name, they could interject files into your file system by sending you malicious emails.
Once you are done updating gmail.conf, restrict access so only root can read or write:
Code:
chmod 600 /etc/gmail.conf
This prevents other users from reading your GMail password!
3.2 Mount GMail file system
First we need to create a mount point for the GMail file system and allow access for any non-root users we would like to use it.
Code:
mkdir /mnt/gmail
chown yourusername.yourgroup /mnt/gmail
note: For security reasons, GMailFS will only allow users to mount to directories owned by them.
Now for the mounting. Update your /etc/fstab file with a text editor and add the line:
Code:
/usr/bin/gmailfs.py /mnt/gmail gmailfs noauto 0 0
you can then mount the GMail file system as with
You can also mount it manually with:
Code:
mount -t gmailfs /usr/bin/gmailfs.py <mount point> -o username=yourusername,password=yourpassword,fsname=yourfsname
4.0 Fine Tuning
Here are some tips on fine tuning the GMail file system that are unnecessary but could be useful.
4.1 Auto Archive GMailFS Messages to Prevent Inbox Clutter
To do this, you will need to log into your GMail account and set up an appropriate filter. You can do this by going to settings->filters->create new filter then add in a filter that will archive everything containing this line in the subject:
Code:
q=__g__<fsname>__h__
I also added one to star every file that contains the previous subject line and has an attachment. This is usefull to me since I use my GMail File System to back up my school/work documents.
4.2 Modify GMailFS to Display True File Name for Email Attachment
Since I wanted to use this to back up my documents and get access to them when I am away from my computer, I was annoyed that GMailFS stored the file attachments by picking a random file name. After a little tinkering, I was able to get the attachment file names to more adequately represent the file.
note:The following instructions requires you to modify the python source code of gmailfs.py. I was able to get it to work (sort of) by reading the code and little trial and error. Use at your own risk.
From reading the source code, it appears that gmailfs.py creates a random file in the memory then copies the actual file to it, then adds the temp file as an attachment. The result is a randomly named file attachment which gives us no clue as to what the file actually is. After looking at tempfile.py in the python lib directory, it looks like you can pass a name to the function instead of using the default random one. Our goal is to change the gmailfs.py source to pass the desired name as a parameter to avoid a random name by default.
Here is what I changed in each method
note: changes are in bold
Code:
#/usr/bin/gmailfs.py
def close(self, path):
...
if self.needsWriting:
self.commitToGmail(path)
...
def write(self, path, buf, off):
...
if self.currentOffset == -1 or off<self.currentOffset or off>self.currentOffset:
self.commitToGmail(path)
...
if self.currentOffset/self.blocksize>currentBlock:
self.needsWriting = 1
self.commitToGmail(path)
...
def commitToGmail(self, path):
...
ind = string.rindex(path,'/')
name = path[ind+1:]
tmpf = tempfile.NamedTemporaryFile('w+b',-1,"",name,None)
...
def write(self, path, buf, off):
...
written = f.write(path,buf,off)
...
def release(self, path, flags):
...
f.close(path)
def fsync(self, path, isfsyncfile)
...
f.commitToGmail(path)
...
The overall strategy here was to find out how the program new what the actual file name was then copy this code into the commitToGmail function, then use it as a parameter when it calls tempfile.NamedTemporaryFile(). Since it uses a variable by the name of 'path' to get the file name, we need to add that as a parameter to the commitToGmail() function, and any function that calls it.
FIXME: The file name to the attachment will display the correct file name + some random letters and #'s at the end. This was the best I could achieve with my lack of knowledge with python. Does anyone that actually knows python have any ideas on how to fix this?
5.0 Change Log
05/21/2006 - First Version, changes to come!
05/22/2006 - added python to system requirements
05/22/2006 - updated overview to give a description of the gmailfs structure
10/25/2006 - cleaned up. checked instructions to make sure they were not outdated.
--------------------------------------------------------