INSTALL (revision 305)

Line	Revision	Contents
1	225	How to run FSP:
2	27	The first step in running this fine software (:) is to get it to
3		compile. Every effort on my part will be made to make this code
4		compile and run on any reasonable system. The information in this
5	225	file CURRENTLY pertains only to Unix and probably to Cygwin users.
6
7		Building:
8		FSP uses SCons software construction tool. Building was tested
9		with SCons 1.2.0 and Python 2.5, but older versions will probably
10		work fine. Prior to building FSP you need to download and install
11		SCons from http://www.scons.org.
12
13	240	Other tools needed for building FSP are GNU flex and GNU C compiler.
14		They should be part of your Unix distribution but you can also
15		download and compile them yourself from http://flex.sourceforge.net/
16		and http://gcc.gnu.org.
17
18	257	For building optional documentation you need sgmlformat-1.7.tar.gz
19		from ftp://ftp1.freebsd.org:/pub/FreeBSD/distfiles and docbook which
20		will be probably already included in your distro.
21
22	225	SCons is replacement for configure and make utility; there is no
23		separate configuration step. Building with SCons is very similar
24		to using make. Run 'scons' to compile and 'scons install' to
25		install. You can skip compile part. 'scons install' will do both
26		steps then.
27
28		SCons can take several optional switches. You must supply these
29		switches to BOTH phases (compile and install) of build process.
30		Most important switch is disable-timeout=yes. This option switches
31		fsp clients into classic infinite retry mode which is preferred
32		by people with very flaky networks.
33
34		>> By default, the SCons will install the code in /usr/local/bin
35		>> and the man pages under /usr/local/man. If you wish to change this,
36		>> you MUST run scons with the prefix option. For instance, on my
37	27	>> machine, I install the files under /usr/jt/bin and /usr/jt/man.
38	226	>> To do this, I type: scons prefix=/usr/jt install
39
40		If you get ANY errors while compiling this code (excepting warnings),
41		please send me email with a complete copy of the output of scons as
42		well as a copy of the config.log file.
43	27
44	227	SCons command line options:
45		prefix=directory set installation directory
46		disable-timeout=yes client utilities never timeouts
47		enable-debug=yes compile in extra debug code
48		enable-lamerpack=yes build lamer pack version of fspd
49		lockprefix=directory set directory for creating client lock files
50		locking=type set locking type, default autodetected
51	228	type is one of none, lockf, semop, flock, shmget
52	227	enable-maintainer-mode=yes compile with libefence debug library and
53		some extra debug information
54		mandir=directory where to install man pages. default autodetect
55		sysconfdir=directory where to look for fspd and client configuration
56	228	files. Default prefix/etc
57	237	without-clients=yes dont build and install client commands
58	228
59	27	Client utilities:
60		All inter-command states are kept in these three shell environment
61		variables.
62
63		FSP_PORT Port number of the fspd you wish to contact.
64		FSP_HOST Host name or number of the fspd.
65		FSP_DIR Your current working directory in the archive.
66
67		When multiple client utilities are run at the same time on the
68		same client machine, packet multiplexing mechanisms can be used
69		to enable concurrent access to the same fsp database. If none
70		of the mechanisms are selected at compile time, FSP_LOCALPORT
71		can be used to ensure that only once client utility can run at
72		any time. In this case, FSP_LOCALPORT can be set to any port
73		number not current used on the client machine.
74
75		FSP_TRACE can be set if you want status reports be printed while
76		files are being transferred.
77
78		FSP_DELAY variable can be used to set the retransmit interval for
79	226	client utilities (in thousandth of a second). This value should be
80		set to slightly higher than average round trip time. The retransmit
81		rate is adjusted in an exponential manner, until the retry rate
82		reaches FSP_MAXDELAY msec per retry. This delay cannot be set
83		below 250 msecs.
84	27
85		FSP_BUF_SIZE can be set to a positive number less than or equal
86		to 1024. When set, it determines the size of data to be send for
87		each request during file and directory information transfer. The
88		default is 1024. Some sites are connected via links that cannot
89		transmit buffers containing 1024 bytes of data in addition to the
90		header information. Setting FSP_BUF_SIZE to a lower value will
91	226	allow these sites to access fsp archives. Large values can provide
92		faster transfers.
93	27
94		FSP_LOCAL_DIR can be set to a local working directory from/to which
95		all data will be transferred.
96
97		Server Administration:
98	226	IMPORTANT NOTE: You do not need to run the fspd process if you only
99		wish to access existing fsp archives. FSPD is only needed if you
100		wish to set up and maintain a new archive for use.
101
102	27	fspd can run independently or it can be run under inetd. When
103		running independently, fspd waits for messages through a UDP
104		socket whoes port number is defined in the fspd.conf file.
105		When runing under inetd, fspd is invoked as in.fspd. Inetd will
106		spawn fspd when a message arrives for the FSP socket. The fspd
107		process will take over and stick around to wait on additional
108	121	messages. After 5 minutes pass with no messages, fspd will exit
109	27	and return control to inted.
110
111		Sample setup for inetd operation:
112
113	256	In /etc/services file:
114
115		fsp 21/udp fspd
116
117		In /etc/inetd.conf file:
118
119		fsp dgram udp wait ftp /usr/local/bin/fspd in.fspd
120
121		In this sample, the same port number for ftp is used for the
122		fsp socket. There will not be a conflict because ftp uses
123		stream protocol, and fsp uses UDP protocol. The fspd program
124		in this example is ran under user 'ftp'.
125	27
126		Many other options controlling the behavior of fspd can be set in
127		the fspd.conf file. Please read the comments in the fspd.conf
128		file for details.
129
130		Clients do not get to read the directory information directly.
131		Instead, fspd maintains a directory listing for each directory
132		in a cache file. If the directory is writable by fspd, or if a
133		writable file in it is prepared beforehand, fspd will store the
134		directory information in .FSP_CONTENT file in that directory.
135
136		When a client requests information for a directory, the cache
137		file is created if it doesn't exist, and it is rebuilt if it is
138		out of date. The information is accessed by having the client
139		read the directory listing file. Care is taken so that the client
140		will not get corrupted entries when the directory is changed while
141		the listing is being read.
142
143		Files being uploaded are first written to a temporary file in the
144		work directory: .TXXXXXXXXYYYY where XXXXXXXX is the inet number
145		of the client, and YYYY is the port number of the client program.
146		When upload is compelete, the file is moved into the intended
147		location.
148
149		Sending it an 'alarm' signal will cause fspd to dump its current
150		client database into the file .HTAB_DUMP in the work directory.
151		This can be useful for debugging and for catching rogue clients.

Loggerhead is a web-based interface for Bazaar branches

SourceForge.net

(root)/fsp/fsp : /INSTALL (revision 305)