forked from Eelis/geordi
-
Notifications
You must be signed in to change notification settings - Fork 3
/
README.xhtml
135 lines (104 loc) · 8.6 KB
/
README.xhtml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.1//EN' 'http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd'>
<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en'>
<head>
<title>Geordi Readme</title>
</head>
<body>
<h1>Geordi Readme</h1>
<hr/><h2>Table of Contents</h2>
<ul>
<li><a href='#installation'>1. Installation</a></li>
<li><a href='#running'>2. Running geordi</a></li>
<li><a href='#localization'>3. Localization</a></li>
<li><a href='#problems'>4. Known problems</a></li>
</ul>
<hr/><h2 id='installation'>1. Installation</h2>
<h3>1.1 Prerequisites</h3>
<ul>
<li>An i386 or x86-64 machine</li>
<li>GNU/Linux ≥ 2.6.34</li>
<li>GCC/G++ ≥ 4.6</li>
<li><a href='http://www.boost.org/'>Boost</a> ≥ 1.33 (Only the headers are needed)</li>
<li><a href='http://www.haskell.org/ghc/'>GHC</a> ≥ 7.4
<!--<p>On Ubuntu, it is highly recommended to use GHC packages from the Ubuntu repositories. Use of haskell.org's GHC packages may result in strange "g++: Virtual timer expired" errors.</p>
<p>Some distributions package GHC libraries separately. If, when compiling, you get errors like “Could not find module "Control.Monad.State"”, look for separate mtl and network packages.</p> -->
</li>
</ul>
<p>In addition, geordi depends on a number of <a href='http://hackage.haskell.org/'>Hackage</a> packages, but these will be downloaded, built, and installed automatically by <a href='http://hackage.haskell.org/trac/hackage/wiki/CabalInstall'>cabal-install</a>.</p>
<h3>1.2 Installing geordi</h3>
<p>The easiest way to build and install geordi is with <a href='http://hackage.haskell.org/trac/hackage/wiki/CabalInstall'>cabal-install</a>, part of the <a href='http://hackage.haskell.org/platform//'>Haskell Platform</a>.</p>
<p>In the geordi directory, say:</p>
<pre> cabal update
cabal install</pre>
<p>This will download, build, and install any missing dependencies from <a href='http://hackage.haskell.org/'>Hackage</a>, and will then build and install geordi (by default into <tt>$HOME/.cabal/</tt>).</p>
<h3>1.3 Setting up a chroot</h3>
<p>To set up a directory for geordi to chroot into when it starts, do the following:</p>
<ol>
<li><p>Edit <kbd>$PREFIX/share/geordi-0/compile-config</kbd> to your liking (where <kbd>$PREFIX</kbd> is the location where Cabal installed geordi, which defaults to <kbd>$HOME/.cabal/</kbd>). Check that the g++ path refers to the actual g++ binary, not some wrapper that adds output coloring or something.</p></li>
<li><p>On Debian and Ubuntu, replace</p><pre> group = "nobody"</pre><p>with</p><pre> group = "nogroup"</pre><p> in <kbd>$PREFIX/share/geordi-0/jail-config</kbd>.</p></li>
<li><kbd>geordi-mkrt</kbd><p>This creates <kbd>$PREFIX/share/geordi-0/rt</kbd>, which will be our chroot root, and copies various files into it that GCC needs in order to function.</p><p>If you ever make further modifications to <kbd>compile-config</kbd>, throw the old <kbd>rt</kbd> away and build a new one with <kbd>geordi-mkrt</kbd> (followed by <kbd>geordi-compile-prelude</kbd>).</p></li>
<li><kbd>geordi-compile-prelude</kbd><p>This compiles the prelude files in <kbd>$PREFIX/share/geordi-0/prelude</kbd> to produce <kbd>$PREFIX/share/geordi-0/rt/{prelude.hpp.gch,prelude.a,libtpreload.so.0.0}</kbd>.</p>
</li>
</ol>
<p>Now try running</p><pre> sudo geordi-local "<< 'x'"</pre>
<p>If this complains about missing executables like <kbd>as</kbd> and <kbd>ld</kbd> which are present in a non-standard location in your <kbd>PATH</kbd>, try</p><pre> sudo env PATH=$PATH geordi-local "<< 'x'"</pre>
<p>If you get errors complaining about missing libraries and such (this can happen due to differing versions or configurations of gcc), try locating those on your system and manually copying them into the corresponding place in <kbd>$PREFIX/share/geordi-0/rt</kbd>.</p>
<p>If your <kbd>compile-config</kbd> points to a custom-built gcc in a non-standard location <kbd>/foo/bar</kbd> and you get an error about <kbd>/t</kbd> missing some libraries, try adding <kbd>-Wl,-rlink,/foo/bar/lib</kbd> to <kbd>LINK_FLAGS</kbd> in <kbd>compile-config</kbd>.</p>
<h3>1.4 Running the testsuite</h3>
<p>A modest testsuite can now be run with <kbd>sudo geordi-testsuite</kbd> (recommended).</p>
<hr/><h2 id='running'>2. Running geordi</h2>
<h3 id='locally'>2.1 <kbd>geordi-local</kbd></h3>
<p><kbd>geordi-local</kbd> lets one test snippets locally (that is, without connecting to any IRC server).</p>
<p>Usage: <kbd>sudo geordi-local [option]... [request]...</kbd></p>
<p>Request syntax is described in the <a href='http://www.eelis.net/geordi/#usage'>manual</a>, except that here the nickname (and colon/comma) must be omitted.</p>
<p>Options:</p>
<dl>
<dt><kbd>-h</kbd> / <kbd>--help</kbd></dt>
<dd><p>Display help and exit.</p></dd>
</dl>
<p>If any requests are specified, they are evaluated and their results are shown. If the first request starts with a request option, interject “<kbd>--</kbd>” to prevent it from being interpreted as a command option.</p>
<p>If no requests are specified, the program goes into a Read-Eval-Print-Loop.</p>
<h3 id='ircbot'>2.2 <kbd>geordi-irc</kbd></h3>
<p>Usage: <kbd>sudo geordi-irc [option]...</kbd></p>
<p>Starting an IRC bot with root permissions should make one seriously nervous. Geordi requires root permissions only because <a href='http://linux.die.net/man/2/chroot'>chroot(2)</a> does. Geordi chroots into <kbd>rt</kbd> as one of the first things it does on startup, and changes to the user and group specified in jail-config before it starts responding to IRC messages.</p>
<p>Options:</p>
<dl>
<dt><kbd>-c <file></kbd> / <kbd>--config <file></kbd></dt>
<dd><p>Load bot configuration from <file> instead of <kbd>irc-config</kbd>.</p></dd>
<dt><kbd>-h</kbd> / <kbd>--help</kbd></dt>
<dd><p>Display help and exit.</p></dd>
</dl>
<h4 id='nickserv'>NickServ identification</h4>
<p>To have the bot identify to NickServ, change the following line in <kbd>irc-config</kbd>:</p>
<pre> , nick_pass = Nothing</pre>
<p>into:</p>
<pre> , nick_pass = Just "mypassword"</pre>
<h4>Nickless requests</h4>
<p>To have the bot respond to nickless requests (e.g. "<kbd><< 3</kbd>") in channels #foo, #bar, and #bas, use:</p>
<pre> , allow_nickless_requests_in = ["#foo", "#bar", "#bas"]</pre>
<h4 id='reconnect'>Auto-reconnect</h4>
<p>Geordi does not auto-reconnect. For that, just use something like</p><pre> while true; do geordi-irc; sleep 120; done</pre>
<h4 id='multinetwork'>Connecting to multiple networks</h4>
<p>Make config files for the different networks. Then run one <kbd>geordi-irc</kbd> instance for each network, passing -c arguments pointing to the respective config files. The <kbd>rt</kbd> directory will be safely shared.</p>
<h4>Censoring phrases</h4>
<p>Some networks automatically kick or ban clients that utter certain phrases (like botnet commands). To prevent a geordi bot from uttering these, list regexes for them in irc-config. E.g.:</p>
<pre> , censor = ["some naughty phrase", "some wicked utterance"]</pre>
<hr/><h2 id='localization'>3. Localization</h2>
<p>To get compiler diagnostics (and some (but not all) other geordi messages) in a locale of your choice, copy the following into <kbd>rt</kbd> (preserving paths, for example using <kbd>cp --parents</kbd>):</p>
<ul>
<li>/usr/lib/locale/foo_BAR.utf8/*</li>
<li>/usr/share/locale/foo/LC_MESSAGES/{cpplib,gcc,libc,libstdc++,opcodes}.mo</li>
</ul>
<p>These paths might differ somewhat on your system.</p>
<p>You may need to install a separate GCC locales package or other kind of language pack for your distro, to get the files above.</p>
<p>Furthermore, not all of the files above may be available for your locale; copy those that are.</p>
<p>Additionally, the LC_ALL environment variable must be set to foo_BAR.utf8 when geordi is started. Note that sudo clears environment variables by default, so either use</p><pre> sudo -E geordi-...</pre><p>or use</p><pre> sudo env LC_ALL=foo_BAR.utf8 geordi-...</pre>
<hr/><h2 id='problems'>4. Known problems</h2>
<ul>
<li>
Because <kbd>geordi-irc</kbd> connects as root, IRC servers that query ident may get a root response and may decide to reject the connection. (Quakenet is known to do this.)
</li>
</ul>
</body>
</html>