Octopod 0.01 User's Guide ------------------------- Octopod is a secure file sharing system. Users can create 'share' directories, whose contents are to be shared with a designated set of other users. Files placed in such directories are automatically made available to the shares' other members, who can, at their option, fetch the actual file data. Octopod consists of two pieces - a command-line tool, octo, and a daemon process, octopod. Start 'octopod' by running it without arguments - it will launch in the background. During operation, octopod will place files with the extension '.oct' in share directories - these files are metadata files that are placeholders for real files in a share. Metadata files can be flagged such that octopod will try to fetch them from other users in a share. Upon retrieval of an actual file, octopod moves the file's metadata into a 'done' directory. Octopod is licenced under the (new) BSD open source license - see the file LICENSE for more details. Compiling --------- Octopod uses autoconf. This means you can just type: ./configure ; make to build it. It has only been tested on recent versions of Linux and MacOS X. Octopod has only one dependency: openssl version 0.9.7e or newer. (To check your openssl version, run 'openssl' and type 'version' at the prompt.) If you run into problems, let me (barath@cs.ucsd.edu) know. Getting started --------------- Octopod requires that each user generate keys and associate with these keys an identity string, which, for example, can be an email address. To init octopod, run: octo -I You will be prompted for your identity string. Upon completion, octo will write the config to your ~/.octopod directory. If you want a summary of all commands, type: octo -h to see a list. Creating shares --------------- To create a share, simply type: octo -n sharedir where 'sharedir' is the name of the directory to hold the share's contents. The share will be assigned an octopod share ID, which looks something like this: octopod://AFDF6833A8990571D14BD305E40DE0C1B8CF9917 Adding users ------------ Once you have created a share, you can add other users to the share by typing: octo -A idstring sharedir where 'idstring' is the identity of the user you want to add to the share and 'sharedir' the directory of that share. The option '-A' (capital A) tells octo to add the user as a writer, whereas '-a' (lowercase a) tells it to add the user with read-only access. If octo is able to find the user's key, it will add them to the share. If it can't find them, you will have to use the '-p' or '-P' option, which specifies the user's key in a keyfile rather than by their identity string. See below for how to extract the keyfile. Joining shares -------------- Once you have been added to a share and know the shareid, you can join the share by typing: octo -j shareid sharedir where 'shareid' is the 'octopod://...' share ID and 'sharedir' is the directory in which you want the share to reside. Extracting your public key -------------------------- It's sometimes necessary to directly send another user your key in case they can't automatically look it up. Do this by typing: octo -E pkfile where 'pkfile' is the name of the file in which to store your public key. You can then send this file to other users, who can add you using the '-p' or '-P' options. Getting file info ----------------- Once part of a share, octopod will place metadata files - '.oct' files - in the share directory. These files contain information about potential files to fetch in that share. You can get information about the actual files by typing: octo -i file1.oct file2.oct ... where 'file1.oct' and 'file2.oct' are metadata files. 'octo' will print the corresponding files' information, including whether or not they are flagged for retrieval (fetchstate = 'fetch' means that the file will be downloaded). Retrieving files ---------------- In the current release of octopod, all metadata files are automatically flagged for retrieval, so no manual marking is required. However, individual files can be marked and unmarked for retrieval by typing: octo -g file1.oct file2.oct ... where 'file1.oct' and 'file2.oct' are the metadata files corresponding to files you wish to either mark or unmark for retrieval. You can specify as many metadata files at a time as you want. Release notes ------------- Currently all files are automatically marked for retrieval. Eventually, 'octo' will allow a per-share toggle of this option. When things go wrong -------------------- In the unfortunate event of a crash or other weird behavior, take a look at ~/.octopod/octopod.log for a log of what octopod was up to. Better yet, send a copy to barath@cs.ucsd.edu with details of your machine (like your compiler and version of openssl). Octo also has a debug option - run any command with '-d' as an extra option and octo will print debugging info.