This post will not be updated any more. To follow Langouste development please visit http://area51dev.blogspot.com
UPDATE: Langouste 15.17 is now available. See CHANGES below for more information.
Linux users: when configuring the client always use 127.0.0.1 as the proxy address;
do _not_ use localhost as it may render client unable to contact Langouste (and, subsequently, upload or download any WUs)
Langouste does upload capping (see section 6)!
Langouste works on Microsoft Windows systems: Windows users are encouraged to read sections 1, 2, 3 and 5
Code: Select all
$ cat README.txt
Contents:
0. License
1. What does Langouste do?
2. How is Langouste useful?
3. Supported configurations (PLEASE READ!)
4. Linux information
4.1. Building Langouste
4.2. Using Langouste
4.3. Upgrading Langouste
4.4. How do I know it's working?
5. Windows information
5.1. Using Langouste
5.2. Upgrading Langouste
5.3. How do I know it's working?
6. Rate limiting (upload capping) feature
6.1. Rate limiting with decoupling (1 Langouste per machine)
7. Known issues and caveats
8. Support
9. Credits
0. License
Langouste is licensed under GNU General Public License version 2.
See COPYING.txt for details.
1. What does Langouste do?
Upon client's attempt to contact collection server (with a WU to return)
it forks a copy of the client (in temporary directory) with -send
parameter and terminates connection "original" client was attempting to
make. If forked client is able to send data back, corresponding
wuresults_*.dat file is wiped from original client's work directory
(so original client's autosend bails out and removes it from queue).
2. How is Langouste useful?
Its intended purpose is to make WU download and return processes
asynchronous (in other words to enable simultaneous downloads and uploads).
Processed SMP and SMP -bigadv WUs are usually large (25-100MB). When WU
processing is complete client sends back the results but new WU is not
retrieved until after upload is complete.
On relatively fast links (1Mbit up) bigadv upload takes ~12 minutes (+5
extra minutes of FAH client/server processing).
Moreover, due to client deficiencies (see
http://foldingforum.org/viewtopic.php?f=44&t=10615) results file cleaning
takes additional time (depending on underlying filesystem -- between
several and 20+ minutes).
As Langouste decouples upload and download processes a new WU can be
downloaded while WU upload continues in background thus saving time.
Time that can be spent on simulation.
3. Supported configurations (PLEASE READ!)
Langouste is supported on modern Linux distributions running Folding@Home
clients 6.02 (32-bit) and 6.34 (64-bit).
Langouste is also supported on 32- and 64-bit Windows running
Folding@Home clients (console, console+GPU, console+SMP, systray, systray+GPU)
6.23, 6.30, 6.41, _not_ in service mode.
Minimal requirement is Windows XP with Service Pack 2. Windows Vista and 7
are also supported.
4. Linux information
4.1. Building Langouste
1. Make sure gcc, make and appropriate development packages are installed
2. Run 'make'
3. Run 'sudo make install' or otherwise run 'make install' as root.
Langouste installs documentation, helper script and rudimentary
SysV initscript to /usr/share/langouste3/. Sample configuration
file is installed to /etc/langouste3/.
4.2. Using Langouste
1. Copy helper script (from /usr/share/langouste3/) to FAH client's
directory
2. Pick a non-used port for Langouste to use (I use 8880)
3. Start Langouste*,**,***: 'langouste3 -l port-from-step-2'
4. Reconfigure FAH client (-config or -configonly)
- set proxy host to 127.0.0.1 (do not leave 'localhost' there)
- set proxy port to port from step 2****
5. Enjoy
*) if you wish to run Langouste in the backgound (otherwise you need
to keep Langouste terminal window open at all times) add -D option
to Langouste's command line, e.g. langouste3 -l port-from-step-2 -D
**) it is _critical_ Langouste is run as the same user as FAH client(s)
(it has no effect otherwise)
***) Langouste also supports reading configuration from a file -- use
'-c' option to specify a file; for configuration options see
langouste.conf.example (located in /etc/langouste3/ after installation)
****) Langouste is designed to handle multiple clients (on same machine) --
running single instance is good enough
4.3. Upgrading Langouste
1. Build and install Langouste per 4.1.
2. Pick a time when FAH client is not sending or receiving data (shutting
client down is not necessary)
3. Terminate existing instance of Langouste
4. Start new instance of Langouste
5. Copy new helper script (from /usr/share/langouste3/) to FAH client
directory
6. Remove old Langouste directory/binary (for safety)
4.4. How do I know it's working?
First off, even if you intend to run Langouste as a daemon (in the
background) running it in the foreground for a while is recommended (just
to make sure things work as expected).
Anyway, the easiest way is to examine forked client's log at (or after)
the time WU is returned (/tmp/langouste directory). See reference log
in dist/linux/reflogs/ directory.
Langouste terminal output follows (informative).
Client (PID 11899) attempts to return a WU but initial connection
is terminated and a new client instance (set up to return the WU) is forked
(via helper script -- PID 11982):
Thu Jun 6 00:45:00 2013 Accepted connection from 127.0.0.1:53282
Thu Jun 6 00:45:00 2013 PID for socket: 11899
Thu Jun 6 00:45:00 2013 PID 11899: issending: 0
Thu Jun 6 00:45:00 2013 (0) Connection from 127.0.0.1:53282 -- slot 0
Thu Jun 6 00:45:00 2013 (0) [FAH] PID 11899 is most likely contacting WU server, content length: 91590673
Thu Jun 6 00:45:00 2013 (0) [FAH] Helper pid: -1
Thu Jun 6 00:45:00 2013 (0) [FAH] PID 11899: numcores: 0
Thu Jun 6 00:45:00 2013 (0) [FAH] now: 1370501100, last helper launched at: 0
Thu Jun 6 00:45:00 2013 (0) [FAH] Launching helper: '/proc/11899/cwd/langouste-helper.sh' (exe name: '/home/folding/fah/fah6')...
Thu Jun 6 00:45:00 2013 (0) [FAH] Forked 11982
Thu Jun 6 00:45:00 2013 (0) Local: received 16384 bytes, sent 0 bytes
Helper output (normally mixed with Langouste output in the terminal -- not logged):
DIRNAME: /proc/11899/cwd
READLINK: /home/folding/fah
BASENAME: langouste-helper.sh
/proc/11899/cwd/langouste-helper.sh: launching asynchronous part, using /home/folding/fah/langouste-helper.sh
As original client doesn't know we're doing anything in the background,
it continues (for a while) its WU return attempts, which are repeatedly
denied by Langouste -- we see the following sequence several times:
Thu Jun 6 00:45:00 2013 Accepted connection from 127.0.0.1:53283
Thu Jun 6 00:45:00 2013 PID for socket: 11899
Thu Jun 6 00:45:00 2013 PID 11899: issending: 0
Thu Jun 6 00:45:00 2013 (0) Connection from 127.0.0.1:53283 -- slot 0
Thu Jun 6 00:45:00 2013 (0) [FAH] PID 11899 is most likely contacting WU server, content length: 91590673
Thu Jun 6 00:45:00 2013 (0) [FAH] Helper pid: -1
Thu Jun 6 00:45:00 2013 (0) [FAH] PID 11899: numcores: 0
Thu Jun 6 00:45:00 2013 (0) [FAH] now: 1370501100, last helper launched at: 1370501100
Thu Jun 6 00:45:00 2013 (0) [FAH] WARNING: can only launch one helper in 2 minutes (per client)
Thu Jun 6 00:45:00 2013 (0) Local: received 16384 bytes, sent 0 bytes
Eventually, original client gives up WU return attempts and initiates
download of a new WU:
Thu Jun 6 00:45:00 2013 Accepted connection from 127.0.0.1:53288
Thu Jun 6 00:45:00 2013 PID for socket: 11899
Thu Jun 6 00:45:00 2013 PID 11899: issending: 0
Thu Jun 6 00:45:00 2013 (0) Connection from 127.0.0.1:53288 -- slot 0
Thu Jun 6 00:45:00 2013 (0) [FAH] PID 11899 is contacting main assignment server
Thu Jun 6 00:45:00 2013 (0) resolving 'assign.stanford.edu:8080'
Thu Jun 6 00:45:00 2013 (0) Connecting to: 171.67.108.200:8080
Thu Jun 6 00:45:00 2013 (0) Connected.
Thu Jun 6 00:45:00 2013 (0) Local connection closed (bsize: 0).
Thu Jun 6 00:45:00 2013 (0) Local: received 559 bytes, sent 396 bytes
Thu Jun 6 00:45:00 2013 (0) Remote: received 396 bytes, sent 559 bytes
Thu Jun 6 00:45:01 2013 Accepted connection from 127.0.0.1:53290
Thu Jun 6 00:45:01 2013 PID for socket: 11899
Thu Jun 6 00:45:01 2013 PID 11899: issending: 0
Thu Jun 6 00:45:01 2013 (0) Connection from 127.0.0.1:53290 -- slot 0
Thu Jun 6 00:45:01 2013 (0) [FAH] PID 11899 is most likely contacting WU server, content length: 512
Thu Jun 6 00:45:01 2013 (0) resolving '128.143.231.201:8080'
Thu Jun 6 00:45:01 2013 (0) Connecting to: 128.143.231.201:8080
Thu Jun 6 00:45:01 2013 (0) Connected.
One minute after first WU return attempt the forked (background) client
kicks in:
Thu Jun 6 00:46:00 2013 Accepted connection from 127.0.0.1:54401
Thu Jun 6 00:46:00 2013 PID for socket: 12011
Thu Jun 6 00:46:00 2013 PID 12011: issending: 1
Thu Jun 6 00:46:00 2013 (1) Connection from 127.0.0.1:54401 -- slot 1
Thu Jun 6 00:46:00 2013 (1) [FAH] PID -1 is most likely contacting WU server, content length: 91590673
Thu Jun 6 00:46:00 2013 (1) resolving '128.143.231.201:8080'
Thu Jun 6 00:46:00 2013 (1) Connecting to: 128.143.231.201:8080
Thu Jun 6 00:46:01 2013 (1) Connected.
Original client completes download of new WU:
Thu Jun 6 00:48:08 2013 (0) Remote connection closed (rbsize: 0).
Thu Jun 6 00:48:08 2013 (0) Local: received 631 bytes, sent 30348818 bytes
Thu Jun 6 00:48:08 2013 (0) Remote: received 30348818 bytes, sent 631 bytes
And, again, tries to return the WU (the one that's already being handled
by the forked client) several times.
Thu Jun 6 00:48:08 2013 Accepted connection from 127.0.0.1:53292
Thu Jun 6 00:48:08 2013 PID for socket: 11899
Thu Jun 6 00:48:08 2013 PID 11899: issending: 0
Thu Jun 6 00:48:08 2013 (0) Connection from 127.0.0.1:53292 -- slot 0
Thu Jun 6 00:48:08 2013 (0) [FAH] PID 11899 is most likely contacting WU server, content length: 91590673
Thu Jun 6 00:48:08 2013 (0) [FAH] Helper pid: 12011
Thu Jun 6 00:48:08 2013 (0) [FAH] PID 11899: numcores: 0
Thu Jun 6 00:48:08 2013 (0) [FAH] Helper (pid 12011) already running
Thu Jun 6 00:48:08 2013 (0) [FAH] If you're sure that's not the case, please remove /tmp/fah/f1
Thu Jun 6 00:48:08 2013 (0) Local: received 16384 bytes, sent 0 bytes
Finally, forked (background) client completes the upload:
Thu Jun 6 00:52:22 2013 (1) Complete request sent.
Thu Jun 6 00:52:22 2013 (1) Remote connection closed (rbsize: 0).
Thu Jun 6 00:52:22 2013 (1) Local: received 91590797 bytes, sent 634 bytes
Thu Jun 6 00:52:22 2013 (1) Remote: received 634 bytes, sent 91590797 bytes
Thu Jun 6 00:52:22 2013 (1) Ratelimit: sent 91590797 byte(s) in 381.824 seconds, 239877 Bps (234.25 kBps)
5. Windows information
5.1. Using Langouste
1. Unzip Langouste archive
2. Copy helper batch file (from dist\win32\ directory) to FAH client's
directory (console) or, if using systray client, to Folding@Home data
files directory
3. Pick a non-used port for Langouste to use (I use 8880)
4. Start cmd.exe
5. Change directory to dist\win32\ subdirectory of the unzipped archive
6. Start Langouste*,**,***: langouste3-15.10.exe -l port-from-step-3
7. Reconfigure FAH client:
- set proxy host to 127.0.0.1 (do not leave 'localhost' there)
- set proxy port to port from step 3****
8. Enjoy
*) it is _critical_ Langouste is run as the same user as FAH client(s)
(it has no effect otherwise)
**) Langouste also supports reading configuration from a file -- use
'-c' option to specify a file; for configuration options see
langouste.conf.example (located in dist/)
***) Langouste also supports reading configuration from a file -- use
'-c' option to specify a file; for configuration options see
langouste.conf.example (located in dist\ directory)
****) Langouste is designed to handle multiple clients (on same machine) --
running single instance is good enough
5.2. Upgrading Langouste
0. Pick a time when FAH client is not sending or receiving data (shutting
client down is not necessary)
1. Terminate existing instance of Langouste with Control+C
2. Start new instance of Langouste
3. Copy new helper script (from dist\win32\ directory) to FAH client
directory (console) or, if using systray client, to Folding@Home data
files directory
4. Remove old Langouste directory/binary (for safety)
5.3. How do I know it's working?
This section is yet to be written. For now, see reference FAH client,
Langouste and Langouste helper logs (captured with version 0.14.1)
in dist\win32\reflogs\ (courtesy of DonMarkoni).
6. Rate limiting (upload capping) feature
Langouste releases 0.15 and later come with a feature that enables user
to limit upload rates.
Capping uploads to as much as 90% of upstream bandwith makes heaven and
earth difference with interactive sessions (ssh et al.) and regular "web
browsing" too -- DNS queries and TCP ACKs require a bit of (ideally
low-latency) upstream bandwidth.
6.1. Rate limiting with decoupling (1 Langouste per machine)
How to? Just add -r <rate-in-bytes-per-second> parameter to you current
command line; see following example (and terminal log):
$ langouste3 -l 8880 -r 240000
Thu Jun 6 00:40:59 2013 Langouste3 15.9 (compiled Thu Jun 6 00:40:52 MDT 2013 by folding@goldfinger)
Thu Jun 6 00:40:59 2013 Langouste3 comes with ABSOLUTELY NO WARRANTY; for details
Thu Jun 6 00:40:59 2013 see `COPYING.txt' file located in source directory
Thu Jun 6 00:40:59 2013 Default Langouste helper temp directory: /tmp/langouste-kszysiu/
Thu Jun 6 00:40:59 2013 Ratelimit: Output rate: 240000 bytes/s (234.37 kBps)
Thu Jun 6 00:40:59 2013 Listening on 127.0.0.1:8880
(...)
Thu Jun 6 00:52:22 2013 (1) Ratelimit: sent 91590797 byte(s) in 381.824 seconds, 239877 Bps (234.25 kBps)
IMPORTANT CAVEAT: multiple machines in the same network won't know about
others' existence;
two (or more) machines returning WUs simultaneously may
(and normally will) exceed limits imposed on any single
machine;
on the other hand, turnaround time of SMP and SMP bigadv
WUs is fairly long so probability of such "clash" isn't
really very high
7. Known issues and caveats
I-1. Using Langouste results in local WU count not being updated; note
that Stanford statistics are _not_ affected by this issue.
Report: http://foldingforum.org/viewtopic.php?f=14&t=11615&start=30#p125534
Comments: updating local WU count is tricky and possible
solutions are prone to variety of race-conditions;
I'm currently reluctant to resolving the issue
at the cost of reliability
8. Support
Using foldingforum.org is recommended. Please post in this thread:
http://foldingforum.org/viewtopic.php?f=14&t=11615
9. Credits
Langouste was written and is maintained by Kris Rusocki <[email protected]>
Special thanks go to:
#area51 crew -- for ideas, test feedback and more
(esp. firedfly for CMD scripting assistance)
Punchy -- for a great deal of troubleshooting assistance, resolving
Langouste's issues on SLES 10 and excellent Windows port
alpha-test feedback
pholcman -- for excellent feedback on rate limiting feature and
general troubleshooting assistance (esp. case with
Langouste residing on other-than-system volume)
DonMarkoni -- for excellent Windows port alpha-test feedback
metal03326 -- for excellent Windows port alpha-test feedback
Blasphemous Cannibal -- for extraordinary amount of persistence
while troubleshooting "infinite loop" issue
Hyperlife -- for help with IPv6 localhost name resolution issue2013-11-25 -- New release (langouste3-15.17)
-- Linux: fixes a bug that could, under very specific circumstances
cause multiple helpers to be launched at WU upload attempts
2013-11-15 -- New release (langouste3-15.16)
-- fixes a bug where oneunit status would not be properly reported after
the client is killed, thanks to Rusty Bowling <[email protected]>
for the report
2013-10-31 -- New release (langouste3-15.15)
-- ensures that post-WU-upload timeout is set at 15 minutes, not 10
2013-10-23 -- New release (langouste3-15.14)
-- improves reliability of 'oneunit' feature
-- automatically turns 'oneunit' feature off after client shutdown
-- Linux: requires root to start/stop Langouste3 service
2013-10-22 -- New release (langouste3-15.13)
-- Linux: fixes a bug related to oneunit mode which could cause multiple
helpers to be launched and impair oneunit mode;
thanks to Rusty Bowling <[email protected]> for report and
troubleshooting help
2013-10-12 -- New release (langouste3-15.12)
-- features oneunit configuration option; it allows users to prevent
client from downloading next WU without restarting the client (client
gets terminated); feature integrates with bundled initscript
-- optimizes accesses to per-PID data
-- more elegantly handles negative numbers provided to enable/disable options
-- refactors/cleans up several code paths
2013-09-30 -- New release (langouste3-15.11)
-- underwent internal reorganization of config file parsing code
-- Linux: adds initial support for control interface (via Unix domain socket)
-- Linux: adds rudimentary control program (langouste3-control)
-- Linux: updates initscript with LSB helper functions
-- extends timestamps from int to time_t where appropriate
2013-08-30 -- New release (langouste3-15.10)
-- adds configuration file support: Langouste can now be configured by
a configuration file (-c command-line option), see sample configuration
file in dist directory for details
-- Linux: adds possibility of running Langouste as specific user (to facilitate
starting Langouste at system startup -- -U command-line option)
-- Linux: includes pidfile support and rudimentary SysV initscript
(needs to be installed manually)
-- adds upstream proxy capability (so Langouste can talk to the world
via HTTP proxy if so desired -- -X command-line option)
-- reorganizes layout of usage information
-- Linux: simplifies code related to lazy signals feature
-- Makefile: installs initscript in /usr/share/langouste3 and sample
configuration file in /etc/langouste3/
-- Makefile: improves 'uninstall' target
2013-06-08 -- New release (langouste3-15.9)
-- Drops leading 0 from version number given maturity of the project
-- Linux: introduces support of 64-bit i-node (socket) numbers;
previous Langouste versions do not decouple uploads if client
socket is assigned a number that exceeds 32 bits (rare occurence)
-- Linux: places helper's work directory in /dev/shm (to mitigate
client's fsync bug)
-- avoids occasional spurious iterations of main loop (harmless issue)
-- increases activity timeout from 5 to 10 minutes
-- reorganizes portions of the code (for easier maintenance)
-- improves certain logging messages
-- adds an option that allows not returning any WUs (shall anyone
want to capture a completed unit)
-- uses more intuitive value as 'max timeout'
-- Linux: simplifies signal handling code
-- Makefile: installs licensing information, documentation and the helper
script to /usr/share/langouste3/
-- Makefile: removes log files on distclean
-- includes minor documentation update
2012-07-29 -- New release (langouste3-0.15.8.1)
-- resolves Windows build issue
-- makes Windows helper script work again (broken in 0.15.8)
-- includes minor spelling fix
2012-04-22 -- Internal release (langouste3-0.15.8)
-- includes all-new robust Makefile, which also allows system-wide
installation (for convenience) on Linux
-- improves on the helper script; now it first tries to return most
recent results (so that possible server issues with old WUs
don't impact most recently completed WUs)
-- improves client-server timeout logic; over last year we've seen
evidence of client and server timeout logic being poorly implemented;
to cope with these issues, Langouste 0.15.8 implements following
timeouts:
- activity timeout (no traffic in either direction while downloading
or uploading): 5 minutes
- post-WU-upload timeout (server's response after completing the upload):
15 minutes
- connect timeout (carried over from past releases): 30 seconds
-- improves ratelimit behavior in case of name resolution delays, scheduling
delays and system time changes (monotonic clock support is coming soon)
-- includes minor code cleanups
2011-04-25 -- New release (langouste3-0.15.7)
-- resolves two major Linux issues; upgrade strongly recommended
-- Linux: resolves issue that could cause Langouste to completely
stop responding once helper script has started (WU return);
such situation would require restart of Langouste
-- Linux: resolves issue that could prevent Langouste from correctly
launching background client; such situation would result
in delayed WU return
-- includes minor documentation update
2010-08-30 -- New release (langouste3-0.15.6)
-- includes two reliability bugfixes (Windows); upgrade is
recommeneded
-- Windows: resolves an issue that could result in Langouste
ceasing to operate and going into infinite loop under
certain conditions (thanks to Blasphemous Cannibal for
troubleshooting assistance)
-- Windows: plugs process handle leak
-- minor cosmetic improvements (compiler warnings, messages)
-- minor documentation tweaks
2010-08-03 -- New release (langouste3-0.15.5)
-- adds reliability improvements: upgrade is recommended
-- Langouste now implements own TCP connection timeout (30s) instead
of relying on FAH client timeout (1h)
-- Linux: improves helper behaviour in a scenario when original client
gets shut down when helper is running
-- Linux: improves behaviour with paths containing whitespace characters
-- Windows: adds support for Langouste residing on drive other system
drive
-- non-zero verbosity levels now use epoch timestamps with microsecond
resolution
-- minor code optimizations and cosmetic fixes
-- adds .txt extension to README, CHANGES and COPYING files (for Windows
users)
-- ACLs now accept CIDR masks
-- ACLs and network mode disabled until release-ready
-- NEW: introduces upload capping feature (see section 6 of README.txt
for more information)
2010-07-19 -- New release (langouste3-0.14.4)
-- Maintenance release
-- Linux: improves robustness in corner-case path and/or client binary names;
updated helper script _must_ be used
-- Windows: fixes (cosmetic) issue that could result in Langouste producing
Winsock errors at shutdown
-- adds missing parameter to Usage/Help screen
-- misc documentation updates
2010-07-18 -- New release (langouste3-0.14.3)
-- Linux: maintenance release; upgrade if you're experiencing issues
related to item below
-- resolves issue that could result in Langouste not being able download
data
-- cleanup: closing all fds after fork has been replaced with FD_CLOEXEC
-- b&w: RX/TX byte counters have been added
-- some messages are now much more informative
-- minor documentation updates have been committed
-- Langouste has been reworked to accommodate Windows porting (porting.c,
core*.c)
-- Langouste is now available for Microsoft Windows platforms!; see README
for details
2010-01-23 -- New release (langouste3-0.12.4)
-- maintenance release; upgrade if you're experiencing issues related
to items below
-- adds logic preventing langouste from handling clients run by other
users
-- adds ownership check of /tmp/fah directory
-- changes langouste TMPDIR to /tmp/langouste-$USER
-- fixes a bug that caused HTTP requests without Content-Length header
be interpreted as a requests with non-zero Content-Length (bug affected
standalone proxy mode; no interference with FAH)
-- cosmetic code improvements
-- minor Makefile tweaks
-- minor documentation updates
2010-01-01 -- New release (langouste3-0.12.2)
-- maintenance release; upgrade if you're experiencing issues related
to items below
-- adds support for SLES 10 (SP2); it uses a different format of socket
entries in /proc/pid/fd (thanks go to bingo-dog for troubleshooting and
initial fix)
-- resolves a bug in socket lookup code that could result (under
certain circumstances) in langouste not being able to find FAH
client's PID; this bug has not been seen in the wild
(thanks go to bingo-dog for identification and initial fix)
-- [advanced users] lazy signals finally work as expected
-- corrects a typo in an error message (found by bingo-dog)
-- tunes up the Makefile
-- adds clarifications to README (langouste needs to be run as the
same user as FAH client(s))
