Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 192 lines (138 sloc) 5.767 kB
638d966 @nicferrier nice formatting, begin an FAQ
authored
1 = Shoes Off =
2
3 Shoes-Off is a simple IRC bouncer written in EmacsLisp.
11e20aa @nicferrier README
authored
4
5 A bouncer is a program that runs on a remote host and provides a sort
6 of proxy irc server. It connects to the real irc server with your
7 nick and authentication details and let's you connect to it (with
8 possibly no security, or different security).
9
10 This bouncer is written using {{{rcirc}}} to make the upstream
11 connection.
12
13
14 == Making it work ==
15
16 Install this or install from the package on marmalade.
17
18 You need to install this in the place you want a bouncer. Not on your
19 local machine (you probably don't want a bouncer there).
20
21 Then define a config, you can customize the variable :
22
23 {{{
24 shoes-off-config
25 }}}
26
27 You can also just setq it with something like:
28
29 {{{
30 (setq shoes-off-config
31 '((:username "bouncer-username"
32 :password "bouncer-password"
33 :server-alist (("irc.upstream.servername"
34 :nick "nick-at-the-irc-network"
35 :port 6667
36 :user-name "user-to-connect-to-the-irc-network"
37 :password "password-to-connect-to-the-irc-network"
38 :full-name "Full Name"
39 :channels ("#channel" "#otherchannel"))))))
40 }}}
41
42 Once that is done you need to start a {{{shoes-off}}} session. A
43 session is the bouncer's upstream connection to the IRC.
44
45 {{{
e03364f @nicferrier updated the README
authored
46 M-x shoes-off-start-session [RET] bouncer-username [RET]
11e20aa @nicferrier README
authored
47 }}}
48
e03364f @nicferrier updated the README
authored
49 Will start the bouncer session.
11e20aa @nicferrier README
authored
50
51 Again on the bouncer, you need to start the bouncer server:
52
53 {{{
54 M-x shoes-off-start [RET] 6901 [RET]
55 }}}
56
57 //6901// is a listener TCP port. It could be anything. Choose wisely.
58
59
e03364f @nicferrier updated the README
authored
60 == Auto-starting the bouncer server ==
61
62 You can auto-start the bouncer server on session start by configuring
63 the {{{shoes-off-server-port}}} variable to be the TCP port you want
64 to start on.
65
11e20aa @nicferrier README
authored
66 == Connecting to a running bouncer ==
67
68 To connect to the running bouncer you need to point your irc client at
69 the port you selected and use the username and password from the
70 {{{shoes-off-config}}}. Here's an {{{rcirc}}} example:
71
72 {{{
73 (rcirc-connect
74 "my-bouncer.example.org" ; hostname of bouncer
75 6901 ; port you started the bouncer on
76 "nick-at-the-irc-network" ; the Nick to use (only used locally)
77 "user-to-connect-to-the-irc-network" ; the username to connect to bouncer
78 "Full Name" ; full name (not used I think)
ac6a5c6 @PuercoPop Update README.creole
PuercoPop authored
79 '("#channel" "#otherchannel") ; start channels (not used I think)
80 "password-to-connect-to-the-irc-network"); the password to connect to bouncer
11e20aa @nicferrier README
authored
81 }}}
82
83 This will connect to the bouncer and everything //should// work.
84
e03364f @nicferrier updated the README
authored
85 == Multiple sessions ==
86
87 Multiple upstream irc sessions can be bounced. This is done by
88 specifying multiple servers in the server-alist and by connecting to
89 services with a qualified username.
90
91 For example, give the config:
92
93 {{{
94 (setq shoes-off-config
95 '((:username "bouncer-username"
96 :password "bouncer-password"
97 :server-alist
98 (("irc-one.upstream.servername"
99 :nick "nick-at-the-irc-network"
100 :port 6667
101 :user-name "user-name-1"
102 :password "password-1"
103 :full-name "Full Name"
104 :channels ("#channel" "#otherchannel"))
105 ("irc-two.upstream.servername"
106 :nick "nick-at-the-irc-network"
107 :port 6667
108 :user-name "user-name-2"
109 :password "password-2"
110 :full-name "Full Name"
111 :channels ("#channelhere"))))))
112 }}}
113
114 You can connect to these with:
115
116 {{{
117 (rcirc-connect
118 "my-bouncer.example.org"
119 6901
120 "bouncer-nick"
121 "bouncer-username@irc-one.upstream.servername"
122 "Full Name"
ac6a5c6 @PuercoPop Update README.creole
PuercoPop authored
123 '("#channel" "#otherchannel")
124 "password")
e03364f @nicferrier updated the README
authored
125 }}}
126
127 for the second one:
128
129 {{{
130 (rcirc-connect
131 "my-bouncer.example.org"
132 6901
133 "bouncer-nick"
134 "bouncer-username@irc-two.upstream.servername"
135 "Full Name"
ac6a5c6 @PuercoPop Update README.creole
PuercoPop authored
136 '("#channel" "#otherchannel")
137 "password")
e03364f @nicferrier updated the README
authored
138 }}}
139
140
ad0968b @nicferrier note the bug that prevents duplicate connections
authored
141 Unfortunately there is a bug at the moment, you can't do that exactly,
142 you must qualify the hostnames, probably by adding host alises to your
143 /etc/hosts file. I will find a way round this.
144
11e20aa @nicferrier README
authored
145 == BUGS ==
146
147 Please report bugs or feature requests to
148 [[https://github.com/nicferrier/shoes-off/issues|GitHub]].
149
150 I'm sure there are loads.
151
152 == Security ==
153
154 **WARNING** this DOES expose your password to the bouncer box. I have
155 made little attempt to secure this right now. IRC is not very
156 secure anyway.
157
158 If you want secure IRC for your team consider
159 [[https://github.com/nfisher/SpikyIRC|SpikyIRC]]
160
161
638d966 @nicferrier nice formatting, begin an FAQ
authored
162 == FAQ ==
163
164 Q How does shoes-off configuration/authentication work?
165
166 A `shoes-off-start-session' is called for a user, that calls
167 `shoes-off/get-config' with the username; this function may have a
168 plugin implementation. It should return the username, password and
169 server-alist for the user. The server-alist are illustrated above.
170
171 When shoes-off needs to check authentication it calls
172 `shoes-off/auth-check' with a username-spec and a password; this
173 function may also have a plugin implementation. If succesfull it
174 should return a transformed name in the manner of
175 `shoes-off/auth-check-impl'.
176
177 Different authentication systems can override the
178 `shoes-off/get-config-plugin' and `shoes-off/auth-plugin' differently
179 to ensure they can hold users and servers in whatever way they like.
180
181
182
183
11e20aa @nicferrier README
authored
184 == Next steps ==
185
186 A lot of work needs to go into automating the startup. But alternately
187 I may just setup a hosting service for bouncers.
188
189 == Why is it called 'Shoes Off'? ==
190
191 Because you have to take your shoes off on a bouncey castle.
Something went wrong with that request. Please try again.