smugfs.4 (6332B)
1 .TH SMUGFS 4 2 .SH NAME 3 smugfs \- file system access to SmugMug photo sharing 4 .SH SYNOPSIS 5 .B smugfs 6 [ 7 .B -DFH 8 ] 9 [ 10 .B -k 11 .I keypattern 12 ] 13 [ 14 .B -m 15 .I mtpt 16 ] 17 [ 18 .B -s 19 .I srvname 20 ] 21 .SH DESCRIPTION 22 .I Smugfs 23 is a user-level file system that provides access to images 24 stored on the SmugMug photo sharing service. 25 It logs in after 26 obtaining a password from 27 .MR factotum (4) 28 using 29 .B server=smugmug.com 30 and 31 .I keypattern 32 (if any) 33 as key criteria 34 (see 35 .MR auth (3) ). 36 Then 37 .I smugfs 38 serves a virtual directory tree mounted at 39 .I mtpt 40 (default 41 .BR /n/smug ) 42 and posted at 43 .I srvname , 44 if the 45 .B -s 46 option is given. 47 .PP 48 The directory tree is arranged in five levels: 49 root, user, category, album, and image. 50 For example, 51 .B /n/smug/cmac/ 52 is a user directory, 53 .B /n/smug/cmac/People/ 54 is a category directory, 55 .B /n/smug/cmac/People/Friends/ 56 is an album directory, 57 and 58 .B /n/smug/cmac/albums/Friends/2631/ 59 is an image directory. 60 .PP 61 SmugMug allows fine-grained classification 62 via subcategories, but subcategories are not yet implemented. 63 .ig 64 Subcategories are inserted as 65 an additional directory level between category 66 and album. 67 [Subcategories are not yet implemented.] 68 .. 69 .PP 70 All directories contain a special control file named 71 .BR ctl ; 72 text commands written to 73 .B ctl 74 change 75 .IR smugfs 's 76 behavior or implement functionality 77 that does not fit nicely into the file system 78 interface. 79 .PP 80 .I Smugfs 81 caches information about users, categories, albums, 82 and images. If changes are made outside of 83 .I smugfs 84 (for example, using a web browser), 85 the cache may need to be discarded. 86 Writing the string 87 .B sync 88 to a directory's 89 .B ctl 90 file causes 91 .I smugfs 92 to discard all cached information used to 93 present that directory and its children. 94 Thus, writing 95 .B sync 96 to the root 97 .B ctl 98 file discards all of 99 .I smugfs 's 100 cached information. 101 .SS "Root directory" 102 The root directory contains directories 103 named after users. 104 By default, it contains only a directory for 105 the logged-in user, but other directories will 106 be created as needed to satisfy directory lookups. 107 .PP 108 In addition to user directories, the root directory 109 contains three special files: 110 .BR ctl , 111 .BR rpclog , 112 and 113 .BR uploads . 114 Reading 115 .B rpclog 116 returns a list of recent RPCs issued to the SmugMug API server. 117 Reads at the end of the file block until a new RPC is issued. 118 The 119 .B uploads 120 file lists the file upload queue (q.v.). 121 .SS "User directories" 122 User directories contain category directories 123 named after the categories. 124 SmugMug pre-defines a variety of categories, 125 so it is common to have many categories that 126 do not contain albums. 127 .PP 128 In a user directory, creating a new directory 129 creates a new category on SmugMug. 130 Similarly, renaming or removing a category 131 directory renames or removes the category on SmugMug. 132 Categories cannot be removed if they contain albums. 133 .PP 134 User directories also contain a directory 135 named 136 .B albums 137 that itself contains all of that user's albums. 138 .SS "Category directories" 139 Each category directory contains album directories 140 named using the album's title. 141 .PP 142 In a category directory, creating a new directory 143 creates a new album on SmugMug. 144 Similarly, renaming or removing an album directory 145 renames or removes the album on SmugMug. 146 Albums cannot be removed if they contain images. 147 .ig 148 .PP 149 Category directories might also contain subcategory directories. 150 Like albums, subcategories can be renamed and removed (when empty). 151 Unlike albums, subcategories cannot be created via ordinary 152 file system operations. 153 Instead, write the command 154 .B subcategory 155 .I name 156 to the category's 157 .B ctl 158 file. 159 .PP 160 Subcategories are identical to categories 161 except that they cannot themselves contain subcategories. 162 .. 163 .SS "Album directories" 164 Each album directory contains image directories 165 named using the image's decimal SmugMug ID. 166 Image directories cannot be created or renamed, 167 but they can be removed. Removing an image directory 168 removes the image from the album on SmugMug. 169 .PP 170 Album directories also contain three special files, 171 .BR ctl , 172 .BR settings , 173 and 174 .BR url . 175 .PP 176 The 177 .B settings 178 file contains the album settings in textual form, 179 one setting per line. 180 Each line represents a single setting and is formatted 181 as an alphabetic setting name followed by a single tab 182 followed by the value. 183 Many settings can be changed by writing new setting lines, 184 in the same format, to the 185 .B settings 186 file. 187 .PP 188 Copying a file into the album directory queues it for 189 uploading to SmugMug to be added to the album. 190 Files disappear from the album directory once they 191 have finished uploading, replaced by new image directories. 192 The 193 .B uploads 194 file in the root directory lists all pending uploads, 195 which are stored temporarily 196 in 197 .BR /var/tmp . 198 .SS "Image directories" 199 Each image directory contains an image file, named 200 with its original name, if available. 201 If the image belongs to another user, SmugMug does not 202 expose the original name, so the file is named 203 .RB \fInnnn\fP .jpg , 204 where 205 .I nnnn 206 is the SmugMug image ID number. 207 The file content is the original image 208 or else the largest image available. 209 .PP 210 The directory contains a 211 .B settings 212 file holding per-image settings, similar to the 213 file in the album directory; 214 and a 215 .B url 216 file, containing URLs to the various sized images 217 on the SmugMug server. 218 .SH EXAMPLES 219 .LP 220 Mount 221 .I smugfs 222 on 223 .BR /n/smug ; 224 the current user must have write access to 225 .B /n/smug 226 and 227 .BR /dev/fuse . 228 .IP 229 .EX 230 % smugfs 231 .EE 232 Watch API calls as they execute: 233 .IP 234 .EX 235 % cat /n/smug/rpclog & 236 .EE 237 Create a new album in the Vacation category 238 and fill it with photos: 239 .IP 240 .EX 241 % mkdir /n/smug/you/Vacation/Summer 242 % cp *.jpg /n/smug/you/Vacation/Summer 243 .EE 244 .LP 245 The photos are now uploading in the background. 246 Wait for the uploads to finish: 247 .IP 248 .EX 249 % while(test -s /n/smug/uploads) sleep 60 250 .EE 251 .LP 252 Make the album publicly viewable and share it. 253 .IP 254 .EX 255 % echo public 1 >/n/smug/you/Vacation/Summer/settings 256 % cat /n/smug/you/Vacation/Summer/url | mail friends 257 .EE 258 .SH SOURCE 259 .B \*9/src/cmd/smugfs 260 .SH SEE ALSO 261 SmugMug, 262 .HR http://smugmug.com/ 263 .SH BUGS 264 .PP 265 If multiple categories or albums have the same name, 266 only one will be accessible via the file system interface. 267 Renaming the accessible one via Unix's 268 .MR mv (1) 269 will resolve the problem. 270 .PP 271 Boolean values appear as 272 .B true 273 and 274 .B false 275 in settings files but must be changed using 276 .B 1 277 and 278 .BR 0 .