man/man4/smugfs.4 - plan9 - Git at Google

 .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
 .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 .
	.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
	.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 .