aboutsummaryrefslogtreecommitdiff
path: root/man/man4/smugfs.4
blob: 4fb8c7f0f97962e26b6bc63f858477f710406ba9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
.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 .