README
1FUSEPod v0.5
2Copyright (C) 2006 Keegan Carruthers-Smith <keegan.csmith@gmail.com>
3
4http://fusepod.sourceforge.net
5
6This is the fifth release of FUSEPod.
7I would really appreciate it if you could send bug reports, feature request,
8praise or dismissal my way at my email address above. I want to make the
9program better. Also any patches are welcome.
10
11Introduction
12============
13
14FUSEPod is a userspace filesystem which mounts your iPod into a directory
15for easy browsing of your songs on your iPod.
16
17Features
18========
19
20 * Read and Write support
21 * Viewing/Removing playlists
22 * Configurable directory layout
23 * Transparent copying of files onto iPod
24 * Tracks have tags in extended attributes
25 * Discovers where your iPod is mounted
26 * Statistics file
27
28Installation
29============
30
31This program has only been tested with Linux 2.6.20, but should work with any
32kernel version that FUSE supports. You require:
33 * FUSE 2.5 or higher (http://sourceforge.net/projects/fuse)
34 * libgpod (www.gtkpod.org) (Tested with 0.3.2 and 0.4.2)
35 * TagLib 1.4 or higher (http://developer.kde.org/~wheeler/taglib/)
36
37Read the file INSTALL for instruction on installing.
38
39Usage
40=====
41
42To mount your ipod type at the console:
43
44 fusepod [mount_to]
45
46If FUSEPod fails to find your iPod you can specify the iPod's mountpoint
47through the environment variable IPOD_DIR. Note that the iPod must already be
48mounted so that you can read it.
49
50For example, say my iPod is mounted at /media/IPOD and I want to mount the
51FUSEPod layer at /home/keegan/ipod
52You would enter at the console:
53
54 IPOD_DIR="/media/IPOD" fusepod /home/keegan/ipod
55
56You can also create the necessary files and directories for your iPod to
57work. FUSEPod will prompt you if you specify IPOD_DIR which does not have
58the necessary structure.
59
60To unmount FUSEPod type at the console:
61
62 fusermount -u [mounted_to]
63
64To add songs copy them too
65
66 [mounted_to]/Transfer
67
68Or add the absolute path of the song to the file
69
70 [mounted_to]/add_songs
71
72You can also add files and recursively add directories through
73
74 [mounted_to]/add_files.sh [ files/directories ] ...
75
76To sync the database and copy the files run
77
78 [mounted_to]/sync_ipod.sh [ -watch ]
79
80The switch -watch will give you status messages while syncing the iPod.
81
82For example, say I was in the [mounted_to] directory. To add a CD to my iPod I
83would type at the command line:
84
85 find /music/Deftones\ -\ BSides\ and\ Rarities > add_songs
86
87Then if I also wanted to add another CD I would type at the command line:
88
89 find /music/Darkest\ Hour\ -\ Undoing\ Ruin >> add_songs
90
91or I could enter at the command line (this is should be in one line)
92
93 ./add_files.sh /music/Deftones\ -\ BSides\ and\ Rarities \
94 /music/Darkest\ Hour\ -\ Undoing\ Ruin
95
96or I could copy files over with cp or a filemanager (Konqueror, Nautilus...)
97into the Transfer directory.
98
99You can the view all the songs that will be added to the iPod by looking
100in the Transfer directory and by running the command (Note songs that can't be
101added will be ignored):
102
103 less add_songs
104
105If you are happy with the contents of add_songs and the Transfer directory you
106can run the command:
107
108 ./sync_ipod.sh
109
110Configuration
111=============
112
113A file containing the directory layout for fusepod is located in you home
114directory in the file .fusepod
115
116The configuration file works by substituting %{letter} with the appropriate tag
117from the song, according to the following table:
118
119 %a = Artist
120 %A = Album
121 %t = Title
122 %g = Genre
123 %T = Track
124 %y = Year
125 %r = Rating
126 %e = File Extension
127
128For example, say you wanted the layout
129
130 /Testing/1/2/3/{Artist}/{Title}.{Extension}
131
132You would write in the .fusepod:
133
134 /Testing/1/2/3/%a/%t.%e
135
136Note that the line has to start with a / character. If you do not have a
137.fusepod in your home directory just run fusepod. (NB. The default .fusepod is
138written on the first run)
139
140License
141=======
142
143See the file COPYING
144
145Authors
146=======
147
148See the file AUTHORS
149
README.fuse
1General Information
2===================
3
4FUSE (Filesystem in Userspace) is a simple interface for userspace
5programs to export a virtual filesystem to the Linux kernel. FUSE
6also aims to provide a secure method for non privileged users to
7create and mount their own filesystem implementations.
8
9You can download the source code releases from
10
11 http://sourceforge.net/projects/fuse
12
13or alternatively you can use CVS to get the very latest development
14version by setting the cvsroot to
15
16 :pserver:anonymous@cvs.sourceforge.net:/cvsroot/fuse
17
18and checking out the 'fuse' module.
19
20Dependencies
21============
22
23Linux kernel version 2.4.X where X >= 21 (some vendor kernels earlier
24than this are also known to work).
25
26Linux kernel version 2.6.X where X >= 0.
27
28Installation
29============
30
31./configure
32make
33make install
34modprobe fuse
35
36You may also need to add '/usr/local/lib' to '/etc/ld.so.conf' and/or
37run ldconfig.
38
39Linux kernels 2.6.14 or later contain FUSE support out of the box. If
40FUSE support is detected, the kernel module in this package will not
41be compiled. It is possible to override this with the
42'--enable-kernel-module' configure option.
43
44If './configure' cannot find the kernel source or it says the kernel
45source should be prepared, you may either try
46
47 ./configure --disable-kernel-module
48
49or if your kernel does not already contain FUSE support, do the
50following:
51
52 - Extract the kernel source to some directory
53
54 - Copy the running kernel's config (usually found in
55 /boot/config-X.Y.Z) to .config at the top of the source tree
56
57 - Run 'make prepare'
58
59For more details see the file 'INSTALL'
60
61How To Use
62==========
63
64FUSE is made up of three main parts:
65
66 - A kernel filesystem module
67
68 - A userspace library
69
70 - A mount/unmount program
71
72
73Here's how to create your very own virtual filesystem in five easy
74steps (after installing FUSE):
75
76 1) Edit the file example/fusexmp.c to do whatever you want...
77
78 2) Build the fusexmp program
79
80 3) run 'example/fusexmp /mnt/fuse -d'
81
82 4) ls -al /mnt/fuse
83
84 5) Be glad
85
86If it doesn't work out, please ask! Also see the file 'include/fuse.h' for
87detailed documentation of the library interface.
88
89Security
90========
91
92If you run 'make install', the fusermount program is installed
93set-user-id to root. This is done to allow normal users to mount
94their own filesystem implementations.
95
96There must however be some limitations, in order to prevent Bad User from
97doing nasty things. Currently those limitations are:
98
99 - The user can only mount on a mountpoint, for which it has write
100 permission
101
102 - The mountpoint is not a sticky directory which isn't owned by the
103 user (like /tmp usually is)
104
105 - No other user (including root) can access the contents of the mounted
106 filesystem.
107
108Configuration
109=============
110
111Some options regarding mount policy can be set in the file
112'/etc/fuse.conf'
113
114Currently these options are:
115
116mount_max = NNN
117
118 Set the maximum number of FUSE mounts allowed to non-root users.
119 The default is 1000.
120
121user_allow_other
122
123 Allow non-root users to specify the 'allow_other' or 'allow_root'
124 mount options.
125
126
127Mount options
128=============
129
130These are FUSE specific mount options that can be specified for all
131filesystems:
132
133default_permissions
134
135 By default FUSE doesn't check file access permissions, the
136 filesystem is free to implement it's access policy or leave it to
137 the underlying file access mechanism (e.g. in case of network
138 filesystems). This option enables permission checking, restricting
139 access based on file mode. This is option is usually useful
140 together with the 'allow_other' mount option.
141
142allow_other
143
144 This option overrides the security measure restricting file access
145 to the user mounting the filesystem. So all users (including root)
146 can access the files. This option is by default only allowed to
147 root, but this restriction can be removed with a configuration
148 option described in the previous section.
149
150allow_root
151
152 This option is similar to 'allow_other' but file access is limited
153 to the user mounting the filesystem and root. This option and
154 'allow_other' are mutually exclusive.
155
156kernel_cache
157
158 This option disables flushing the cache of the file contents on
159 every open(). This should only be enabled on filesystems, where the
160 file data is never changed externally (not through the mounted FUSE
161 filesystem). Thus it is not suitable for network filesystems and
162 other "intermediate" filesystems.
163
164 NOTE: if this option is not specified (and neither 'direct_io') data
165 is still cached after the open(), so a read() system call will not
166 always initiate a read operation.
167
168large_read
169
170 Issue large read requests. This can improve performance for some
171 filesystems, but can also degrade performance. This option is only
172 useful on 2.4.X kernels, as on 2.6 kernels requests size is
173 automatically determined for optimum performance.
174
175direct_io
176
177 This option disables the use of page cache (file content cache) in
178 the kernel for this filesystem. This has several affects:
179
180 - Each read() or write() system call will initiate one or more
181 read or write operations, data will not be cached in the
182 kernel.
183
184 - The return value of the read() and write() system calls will
185 correspond to the return values of the read and write
186 operations. This is useful for example if the file size is not
187 known in advance (before reading it).
188
189max_read=N
190
191 With this option the maximum size of read operations can be set.
192 The default is infinite. Note that the size of read requests is
193 limited anyway to 32 pages (which is 128kbyte on i386).
194
195hard_remove
196
197 The default behavior is that if an open file is deleted, the file is
198 renamed to a hidden file (.fuse_hiddenXXX), and only removed when
199 the file is finally released. This relieves the filesystem
200 implementation of having to deal with this problem. This option
201 disables the hiding behavior, and files are removed immediately in
202 an unlink operation (or in a rename operation which overwrites an
203 existing file).
204
205 It is recommended that you not use the hard_remove option. When
206 hard_remove is set, the following libc functions fail on unlinked
207 files (returning errno of ENOENT):
208 - read()
209 - write()
210 - fsync()
211 - close()
212 - f*xattr()
213 - ftruncate()
214 - fstat()
215 - fchmod()
216 - fchown()
217
218debug
219
220 Turns on debug information printing by the library.
221
222fsname=NAME
223
224 Sets the filesystem name. The default is the program name.
225
226use_ino
227
228 Honor the 'st_ino' field in getattr() and fill_dir(). This value is
229 used to fill in the 'st_ino' field in the stat()/lstat()/fstat()
230 functions and the 'd_ino' field in the readdir() function. The
231 filesystem does not have to guarantee uniqueness, however some
232 applications rely on this value being unique for the whole
233 filesystem.
234
235readdir_ino
236
237 If 'use_ino' option is not given, still try to fill in the 'd_ino'
238 field in readdir(). If the name was previously looked up, and is
239 still in the cache, the inode number found there will be used.
240 Otherwise it will be set to '-1'. If 'use_ino' option is given,
241 this option is ignored.
242
243nonempty
244
245 Allows mounts over a non-empty file or directory. By default these
246 mounts are rejected (from version 2.3.1) to prevent accidental
247 covering up of data, which could for example prevent automatic
248 backup.
249
250umask=M
251
252 Override the permission bits in 'st_mode' set by the filesystem.
253 The resulting permission bits are the ones missing from the given
254 umask value. The value is given in octal representation.
255
256uid=N
257
258 Override the 'st_uid' field set by the filesystem.
259
260gid=N
261
262 Override the 'st_gid' field set by the filesystem.
263