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 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363
|
Copyright (c) 2010-2017 The SquirrelMail Project Team
Copyright (c) 2002-2010 Dave McMurtrie
This directory contains the source distribution of SquirrelMail IMAP Proxy.
If you find any bugs in imapproxy, please subscribe to the
squirrelmail-imapproxy mailing list and post your bug there.
If you want to subscribe to the squirrelmail-imapproxy mailing list, visit:
https://lists.sourceforge.net/lists/listinfo/squirrelmail-imapproxy
To read a little bit about SSL support in imapproxy, read README.ssl.
You'll need to edit the global configuration file to suit your needs. By
default, the proxy server looks at /etc/imapproxy.conf as its configuration
file. You can change this at runtime by supplying the -f argument to
imapproxyd.
pimpstat is the Polling IMAP Mail Proxy Statistical tool. It's a curses-based
application that you can use to monitor the proxy server. It's aware of the
same global configuration file as the proxy server, and can also be told to
look at a different configuration file by supplying it as a parameter with the
-f argument. Both pimpstat and imapproxyd must be using the same
configuration file, since the stat file that they both rely on is set in the
configuration file.
##############################################################################
CONFIGURATION OPTIONS
##############################################################################
server_hostname
---------------
This determines which IMAP server you want to proxy connections to.
cache_size
----------
A slightly misleading configuration option. It's really the total number of
in-core connections that the server can handle, so it will include all of the
active connections and all of the cached connections. For performance, no
memory is dynamically allocated within the proxy server once it starts to
accept connections. That means that all of the IMAP connection structures have
to be allocated at server startup. This configuration setting allows you to
control how many of these structures are allocated. The higher you make this
number, the more memory the server will allocate. Also, since the proxy
server is multi-threaded it will need to increase the total number of allowed
file descriptors it can have open. We run with a default setting of 3072
here. I don't know how big you can make this number before you'd have
problems with setrlimit().
listen_port
-----------
The port that the server binds to and accepts connections on. This is the
tcp port that IMAP clients will connect to.
cache_expiration_time
---------------------
This is the number of seconds that we keep a connection open to the IMAP server
after a client logs out. Once a client logs out, the in-core IMAP connection
structure is marked as "cached" instead of "active" and a timestamp is set on
the structure. Once "cache_expiration_time" seconds have elapsed, this
connection to the server will be closed and any future logins from the user
that was connected on this socket will require a new connection to the server.
proc_username
-------------
The proxy server will NOT run as root. This is quite simply for security
reasons. You can specify which user you want the proxy to run as here.
proc_groupname
--------------
This is the groupname that the proxy server will run as.
stat_filename
-------------
The proxy server opens a file and mmap()s a statistical structure when it
starts. It keeps some really simple numbers in here. You can use the
pimpstat application to display these numbers and monitor the usage of the
proxy server.
protocol_log_filename
---------------------
The proxy server allows you to turn on protocol logging on a per-user basis.
All proxied traffic for one user will be logged to this file, differentiated
by client or server. This file is opened at server startup, and is held open
until the server is shut down.
syslog_facility
---------------
The logging facility to be used for all syslog calls. Any of the possible
facilities listed in the syslog(3C) manpage may be specified here except
for LOG_KERN.
syslog_prioritymask
-------------------
The syslog LOG_UPT() priority mask. Read more about what this does in the
syslog(3C) manpage. Any of the possible priorities specified in the
syslog(3C) manpage my be specified here.
send_tcp_keepalives
-------------------
Allows tcp keepalives to be enabled on all sockets if the tcp implementation
supports it.
tls_ca_file
-----------
File containing one or more Certificate Authority (CA) certificates.
See README.ssl for more information.
tls_ca_path
-----------
Path to directory with certificates of CAs. This directory must have
filenames with the hashed value of the certificate (see openssl(1)).
See README.ssl for more information.
tls_cert_file
-------------
File containing the certificate presented by imapproxy to the server for
client authentication during STARTTLS. See README.ssl for more information.
tls_key_file
------------
File containing the private key belonging to the client certificate. See
README.ssl for more information.
tls_verify_server
-----------------
Indicates that the server's TLS certificate must be verified. See
README.ssl for more information.
tls_ciphers
-----------
Allows you to manually specify TLS cipher suite as documented in openssl
ciphers(1). See README.ssl for more information.
tls_no_tlsv1
------------
Prevents the usage of TLS v1 (SSL v2 and v3 are already forbidden, which
is hard coded). See README.ssl for more information.
tls_no_tlsv1.1
--------------
Prevents the usage of TLS v1.1 (SSL v2 and v3 are already forbidden, which
is hard coded). See README.ssl for more information.
tls_no_tlsv1.2
--------------
Prevents the usage of TLS v1.2 (SSL v2 and v3 are already forbidden, which
is hard coded). See README.ssl for more information.
force_tls
---------
Requires STARTTLS support by the server (won't use unsecured connections).
See README.ssl for more information.
enable_select_cache
-------------------
Allows SELECT data caching to be enabled or disabled.
foreground_mode
---------------
When enabled, this will prevent imapproxy from detaching from his parent
process and controlling terminal.
chroot_directory
----------------
If this value is set to anything, it implicitly causes imapproxy to run in a
chroot jail.
enable_admin_commands
---------------------
The internal admin commands that imapproxy provides (p_dumpicc, p_trace, etc.)
are a security vulnerability if you do not restrict access to the listen_port
using tcp wrappers, iptables, ipchains, ipfilter, an external firewall, or
some other mechanism. Because of this, the internal admin commands are
disabled by default.
##############################################################################
NEW STATUS RESPONSE:
##############################################################################
Upon a successful LOGIN or AUTHENTICATION, if imapproxy reused an existing
connection an untagged IMAP response with the status response XPROXYREUSE will
be issued. This status response indicates to a client that any previous
initialization does not need to be performed again.
Examples:
---------
1. Login without an active cached connection.
C: a001 LOGIN user password
S: [... untagged response(s) from remote IMAP server ...]
S: a001 OK User logged in
2. Login with an active cached connection.
C: a001 LOGIN user password
S: [... untagged response(s) from remote IMAP server ...]
S: * OK [XPROXYREUSE] IMAP connection reused by imapproxy
S: a001 OK User logged in
##############################################################################
ADDITIONAL COMMANDS:
##############################################################################
There are a few additional commands that have been added to allow you to
administer the proxy server. They're implemented through the same mechanism
as regular IMAP protocol commands, so they require you to telnet to your
proxy server on whatever port you choose to bind to and type them like a
regular protocol transaction. At our site, we've severely limited access to
the proxy port such that only our webmail machines and one internal admin
machine can access it. The proxy server software offers no way to limit the
usage of these commands by username so they're not implemented by default.
If you secure the listen_port, you can then set the enable_admin_commands
option in imapproxy.conf to enable the use of these commands.
These commands are available only until you log into the remote IMAP server.
If these commands are available, the string 'XIMAPPROXY' will be listed in
the CAPABILITY string before login/authentication (see RFC 3501 [6.1.1]).
These commands are prefixed with 'X' to comply with RFC 3501 [6.5.1].
XPROXY_NEWLOG
-------------
Since the protocol log file is held open as long as the server is running,
it's difficult to clear the logfile. This command was added to take care of
that for you.
Usage:
<tag> XPROXY_NEWLOG
Example:
C: a001 XPROXY_NEWLOG
S: a001 OK Logfile cleared
XPROXY_DUMPICC
--------------
The Dump ICC command allows you to display the internal data structures of the
proxy server. It can tell you how many connections you currently have open,
what users they're for, and the status of the connections (active or cached).
Use this sparingly if the proxy server is extremely busy.
Usage:
<tag> XPROXY_DUMPICC
Untagged response(s) (1 for each cached connection):
* XPROXY_DUMPICC <#> <user> <status>
<#> = socket descriptor of IMAP connection to backend server
<user> = Username of connection
<status> = Either 'Active' or 'Cached'
Example:
C: a001 XPROXY_DUMPICC
S: * XPROXY_DUMPICC 1 foo Cached
S: * XPROXY_DUMPICC 2 foo2 Active
S: a001 OK Completed
XPROXY_TRACE
------------
This is used to turn on or off protocol logging. If issued without any
arguments, it will disable protocol logging. If issued with a username
argument, it will turn on logging for that particular user. Protocol log
output will show up in the file configured as "protocol_log_filename" in the
configuration file.
Usage:
<tag> XPROXY_TRACE [user]
[user] = (OPTIONAL) Username to log
Examples:
C: a001 XPROXY_TRACE
S: a001 OK Tracing disabled
C: a001 XPROXY_TRACE foo
S: a001 OK Tracing enabled for user foo
XPROXY_RESETCOUNTERS
--------------------
This allows you to reset the internal counters that pimpstat reports on
without having to restart the server. These are the counters that are mmap()ed
to the file configured as "stat_filename" in the configuration file.
Usage:
<tag> XPROXY_RESETCOUNTERS
Example:
C: a001 XPROXY_RESETCOUNTERS
S: a001 OK Counters reset
XPROXY_VERSION
--------------
This is used to show the version number of the IMAP proxy.
Usage:
<tag> XPROXY_VERSION
Untagged response(s) (1 for each cached connection):
* XPROXY_VERSION <version>
<version> = Current version number of imapproxy.
Example:
C: a001 XPROXY_VERSION
S: * XPROXY_VERSION 1.2.6
S: a001 OK Completed
ID
--
This is not a command specific to imapproxy, rather it comes from RFC 2971.
It is listed here because the ID command may be sent before the client
authenticates, which means the proxy server handles it - sort of. Any ID
commands still need to be sent to the IMAP server, so the proxy responds
with a fake "OK" and queues the ID commands to be sent once a LOGIN or
AUTHENTICATE is received from the client and a server connection is
(re)established.
Usage:
<tag> ID [(parameter list)]
[(parameter list)] = (OPTIONAL) Parameters to be sent to IMAP server
See RFC 2971.
Examples:
C: a001 ID
S: a001 OK Completed
C: a001 ID ("x-originating-ip" "10.10.1.2")
S: a001 OK Completed
Responses above from the proxy server are faked and do not necessarily
indicate that the IMAP server will accept the ID commands. If an ID
command fails when sent to the IMAP server, the proxy server will log
a problem that includes the string "QUEUED PREAUTH failed".
Any ID commands sent by the client AFTER login/authentication are
always sent directly through to the IMAP server and are never handled
by the proxy server.
NOTE: Currently only the last ID command received before client login
is remembered and relayed to the server. Please let us know if you
find this insufficient.
Happy proxying,
The SquirrelMail Project Team
|