path: root/man/man4/smugfs.4

.TH SMUGFS 4
.SH NAME
smugfs \- file system access to SmugMug photo sharing
.SH SYNOPSIS
.B smugfs
[
.B -DFH
]
[
.B -k
.I keypattern
]
[
.B -m
.I mtpt
]
[
.B -s
.I srvname
]
.SH DESCRIPTION
.I Smugfs
is a user-level file system that provides access to images
stored on the SmugMug photo sharing service.
It logs in after
obtaining a password from 
.IR factotum (4)
using
.B server=smugmug.com
and
.I keypattern
(if any)
as key criteria
(see
.IR auth (3)).
Then 
.I smugfs
serves a virtual directory tree mounted at
.I mtpt
(default
.BR /n/smug )
and posted at 
.I srvname ,
if the 
.B -s
option is given.
.PP
The directory tree is arranged in five levels:
root, user, category, album, and image.
For example,
.B /n/smug/cmac/
is a user directory,
.B /n/smug/cmac/People/
is a category directory,
.B /n/smug/cmac/People/Friends/
is an album directory,
and
.B /n/smug/cmac/albums/Friends/2631/
is an image directory.
.PP
SmugMug allows fine-grained classification
via subcategories, but subcategories are not yet implemented.
.ig
  Subcategories are inserted as
an additional directory level between category 
and album.
[Subcategories are not yet implemented.]
..
.PP
All directories contain a special control file named
.BR ctl ;
text commands written to 
.B ctl
change 
.IR smugfs 's
behavior or implement functionality
that does not fit nicely into the file system
interface.
.PP
.I Smugfs
caches information about users, categories, albums,
and images.  If changes are made outside of
.I smugfs
(for example, using a web browser),
the cache may need to be discarded.
Writing the string
.B sync
to a directory's
.B ctl
file causes
.I smugfs
to discard all cached information used to
present that directory and its children.
Thus, writing
.B sync
to the root
.B ctl
file discards all of
.I smugfs 's
cached information.
.SS "Root directory"
The root directory contains directories
named after users.
By default, it contains only a directory for
the logged-in user, but other directories will
be created as needed to satisfy directory lookups.
.PP
In addition to user directories, the root directory
contains three special files:
.BR ctl ,
.BR rpclog ,
and
.BR uploads .
Reading
.B rpclog
returns a list of recent RPCs issued to the SmugMug API server.
Reads at the end of the file block until a new RPC is issued.
The
.B uploads
file lists the file upload queue (q.v.).
.SS "User directories"
User directories contain category directories
named after the categories.
SmugMug pre-defines a variety of categories,
so it is common to have many categories that
do not contain albums.
.PP
In a user directory, creating a new directory
creates a new category on SmugMug.
Similarly, renaming or removing a category
directory renames or removes the category on SmugMug.
Categories cannot be removed if they contain albums.
.PP
User directories also contain a directory
named
.B albums
that itself contains all of that user's albums.
.SS "Category directories"
Each category directory contains album directories
named using the album's title.
.PP
In a category directory, creating a new directory
creates a new album on SmugMug.
Similarly, renaming or removing an album directory
renames or removes the album on SmugMug.
Albums cannot be removed if they contain images.
.ig
.PP
Category directories might also contain subcategory directories.
Like albums, subcategories can be renamed and removed (when empty).
Unlike albums, subcategories cannot be created via ordinary
file system operations.
Instead, write the command
.B subcategory
.I name
to the category's
.B ctl
file.
.PP
Subcategories are identical to categories
except that they cannot themselves contain subcategories.
..
.SS "Album directories"
Each album directory contains image directories
named using the image's decimal SmugMug ID.
Image directories cannot be created or renamed,
but they can be removed.  Removing an image directory
removes the image from the album on SmugMug.
.PP
Album directories also contain three special files,
.BR ctl ,
.BR settings ,
and
.BR url .
.PP
The
.B settings
file contains the album settings in textual form,
one setting per line.
Each line represents a single setting and is formatted
as an alphabetic setting name followed by a single tab
followed by the value.
Many settings can be changed by writing new setting lines,
in the same format, to the
.B settings
file.
.PP
Copying a file into the album directory queues it for
uploading to SmugMug to be added to the album.
Files disappear from the album directory once they
have finished uploading, replaced by new image directories.
The 
.B uploads
file in the root directory lists all pending uploads,
which are stored temporarily
in 
.BR /var/tmp .
.SS "Image directories"
Each image directory contains an image file, named
with its original name, if available.
If the image belongs to another user, SmugMug does not
expose the original name, so the file is named
.RB \fInnnn\fP .jpg ,
where
.I nnnn
is the SmugMug image ID number.
The file content is the original image
or else the largest image available.
.PP
The directory contains a 
.B settings
file holding per-image settings, similar to the 
file in the album directory;
and a
.B url
file, containing URLs to the various sized images
on the SmugMug server.
.SH EXAMPLES
.LP
Mount
.I smugfs
on
.BR /n/smug ;
the current user must have write access to 
.B /n/smug
and
.BR /dev/fuse .
.IP
.EX
% smugfs
.EE
Watch API calls as they execute:
.IP
.EX
% cat /n/smug/rpclog &
.EE
Create a new album in the Vacation category
and fill it with photos:
.IP
.EX
% mkdir /n/smug/you/Vacation/Summer
% cp *.jpg /n/smug/you/Vacation/Summer
.EE
.LP
The photos are now uploading in the background.
Wait for the uploads to finish:
.IP
.EX
% while(test -s /n/smug/uploads) sleep 60
.EE
.LP
Make the album publicly viewable and share it.
.IP
.EX
% echo public 1 >/n/smug/you/Vacation/Summer/settings
% cat /n/smug/you/Vacation/Summer/url | mail friends
.EE
.SH SOURCE
.B \*9/src/cmd/smugfs
.SH SEE ALSO
SmugMug, 
.HR http://smugmug.com/
.SH BUGS
.PP
If multiple categories or albums have the same name,
only one will be accessible via the file system interface.
Renaming the accessible one via Unix's
.IR mv (1)
will resolve the problem.
.PP
Boolean values appear as
.B true
and
.B false
in settings files but must be changed using
.B 1
and
.BR 0 .