ezbounce v2.0 File Library --------------------------------------------------------- Last Updated: $Date: 2008-03-31 18:21:57 -0500 (Mon, 31 Mar 2008) $ 1. Introduction The ezbounce file library allows users to store files on the system the proxy is running on. It provides a Unix filesystem-like directory hierarchy with each user having a home directory. In addition, it supports file ownership and permissions, also modeled after Unix, providing a familiar privacy and security model among proxy users. The files can be downloaded, sent to others on IRC, renamed, erased, just like a normal file system. Currently IRC chat logs and the user Event Log are stored in the file library. In addition, users may DCC Send files to the proxy for storage in the file library, and store DCC transfers from other IRC users on the proxy for later retrieval. 2. Differences from Earlier Version In ezbounce v1.0 there was no file library, but rather a directory where users' IRC chat logs were stored. The metadata for the files (owner, password, etc.) was encoded in the filename through a crude mechanism. In the unfinished 1.50 series, a simple file library was introduced which essentially gave each user his own directory where chat logs and other files could be stored. This directory was private and not accessible to (or sharable with) anyone else. In v2.0, a virtual Unix-like filesystem is implemented, complete with a common directory structure, user/group credentials, and access permissions. 3. Configuration Setup involves defining the File Library directory, and then configuring access settings for individual users. 3.1. Proxy Configuration Here is the first configuration option that must be set in the config file: set filelib-dir As the name suggests, this is the directory where the file library and its database files will reside. You might want to create a "filelib" directory in your ezbounce directory and use that. 3.2. User Configuration The following are *user* options (meaning they must go inside user { } blocks in the configuration file): set enable-filelib-access <1/0> If set to 1, this lets a user access the library. Otherwise, the user will not have *any* access to the file library and features requiring it, such as chat logging. set is-filelib-superuser <1/0> If set to 1, grants superuser access to the user. Like the Unix superuser (aka "root"), this gives complete access to any file or directory (with very exceptions; see below). Note that proxy admins are, by default, superusers. Thus you may use this option to take away superuser privileges from an admin. The option is ignored for non-admin users. set enable-dcc-storage <1/0> If enabled, the user can upload files to the proxy via DCC Send and store them in the file library. He can also store incoming DCC transfers from other users on IRC. set filelib-quota Specifies a quota for a user. Use 0 for no quota. NOTE: support for quotas is currently broken. Here's an example configuration that creates a file library in the "filelib/" directory and defines two users - one with acecss, and one without. set filelib-dir "filelib/" user "joe" { ... set enable-filelib-access 1 set enable-dcc-storage 1 ... other options } # No file library access permissions. user "bob" { set enable-filelib-access 0 ... other options } 4. Accessing the File Library 4.1. Basic Directory Setup The file library resembles a typical Unix file system, with each user getting a default home directory setup like this: /home/joe/dcc-in/ /home/joe/dcc-out/ /home/joe/logs/ 4.2. Accessing Files The 'file' command is used for all file library accesses. It has several subcommands which should be familiar to Unix users: ls, chmod, rm, mv, cd, pwd, and others. For more information, type '/ezb help file' 4.3. Retrieving Files Users may retrieve files via DCC Send. For example: /ezb file get /home/bob/file.txt File may also be viewed through DCC Chat. An example: /ezb file view /home/bob/file.txt 4.4. Sending Files to Others Files may be sent to users on IRC. Use the 'file send' command for this: /ezb file send joe /home/bob/file.txt This will cause the proxy to DCC send file.txt to "joe" on IRC. There is also a 'file show' command which will open a DCC Chat to a user and display a file's contents: /ezb file show joe /home/bob/file.txt 4.5. Deleting Files Files may be deleted with the 'file rm' command. 4.6. Moving Files TODO: Not implemented yet. 4.7. Copying Files TODO: Not implemented yet. 4.8. Changing Permissions Permissions may be changed via the 'file chmod' command, which works just like the chmod command found on Unix-like systems (in fact, the parsing code it uses is borrowed from GNU Coreutils). For more information on the security model, see the Details section below. 4.9. Changing Special Attributes TODO: add this section 5. Details 5.1. Credentials A user/group credential system is used, similar to Unix. Each ezbounce user gets a file library username which is equivalent to his ezbounce account name. He also belongs to a group by that name as well as the "users" group. Thus, user "joe" would be in the groups "joe" and "users." 5.2. Permissions Unix-style permissions are used. This is the standard "user, group, others" class setup with read-write-execute bits. Permissions may be viewed with the 'file info' or 'file ls' commands, and set with 'file chmod'. If you need more information, see http://en.wikipedia.org/wiki/Unix_permissions 5.3. Special Attributes In addition to permissions, files may be assigned special attributes. Currently the only attribute supported is "private." Files marked as private are only readable or modifiable by the user that owns them. No one else may access them, regardless of the permissions set on the file. This applies to superusers as well, but note that superusers will still be allowed to erase the file. This is mainly to provide additional privacy for users' log files. Keep in mind that on the host system itself, the files will belong to whoever is running the proxy, and he (and possibly others) will have full access to them that way. NOTE: Special attribute support is still in progress. NOTE: In the future, I would like to add encryption support for chat logs (and possibly for arbitrary files in the file library). It is likely the 'private' attribute will then be removed, as encryption would provide a superior solution for privacy. 5.4. Superusers As mentioned above, superusers have full access to the file library, much like the "root" account in Unix. There is only one exception -- they may not read any file they do not own which has been marked as "Private." This is a special attribute which users may assign to their files, and is assigned by default to certain ones like chat logs. Superusers can't read these files, change their ownership or permissions, but they can still erase them. By default, all proxy admins are also file library superusers. This may not be desirable for all cases, so a configuration option is provided to disable this. See the above section for "User Configuration." Non-admins cannot be superusers. 6. Notes 6.1. Security Issues Great care has been taken to ensure that all file library accesses are fully contained within the on-disk file library directory structure. That is, proxy users must never be allowed to access arbitrary files on the host system; they may only access those under the file library root directory. All paths accessed are normalized to prevent "escaping" the root directory. Also, any symbolic links found inside the file library are ignored, and any path found to contain them is rejected. On the host system, files will be stored with 0600 permissions, and directories with 0700 permissions. 6.2. Implementation The file listings and metadata are stored in a simple database file. The database file format is binary and may not be portable across platforms. The file library is *not* designed to be shared between concurrently running instances of ezbounce. Only one instance of the program can safely access the file library database files at a time. While database files are locked before each access, concurrent access attempts could still result in other internal errors. Source code for the implementation is under src/fs. 6.3. Future Directions Who knows.