1CNTLM(1) Accelerating NTLM/NTLMv2 Authentication Proxy CNTLM(1)
2
6 cntlm - authenticating HTTP(S) proxy with TCP/IP tunneling and acceler‐
7 ation
8
11 cntlm [ -AaBcDdFfgHhILlMPprSsTUuvw ] [ host1 port1 | host1:port1 ] ...
12 hostN portN
13
16 Cntlm is an NTLM/NTLMv2 authenticating HTTP proxy. It takes the address
17 of your proxy or proxies (host1..N and port1..N) and opens a listening
18 socket, forwarding each request to the parent proxy (moving in a circu‐
19 lar list if the active parent stops working). Along the way, a connec‐
20 tion to the parent is created anew and authenticated or, if available,
21 previously cached connection is reused to achieve higher efficiency and
22 faster responses. When the chain is set up, cntlm should be used as a
23 proxy in your applications. Cntlm also integrates transparent TCP/IP
24 port forwarding (tunneling) through the parent (incl. authentication).
25 Each tunnel opens a new listening socket on the defined local port and
26 forwards all connections to the given host:port behind the secondary
27 proxy. Manual page explains how to setup cntlm properly using configu‐
28 ration file or command-line arguments.
29 Cntlm works similarly to NTLMAPS, plus full NTLM support, a bucket of
32 new features and none of its shortcomings and inefficiencies. It adds
33 support for real keep-alive (on both sides) and it caches all authenti‐
34 cated connections for reuse in subsequent requests. It can be restarted
35 without TIME_WAIT delay, uses just a fraction of memory compared to
36 NTLMAPS and by orders of magnitude less CPU. Each thread is completely
37 independent and one cannot block another. Cntlm has many security/pri‐
38 vacy features like NTLMv2 support and password protection - it is pos‐
39 sible to substitute password hashes (which can be obtained using -H)
40 for the actual password or to enter the password interactively. If
41 plaintext password is used, it is automatically hashed during the
42 startup and all its traces are removed from the process memory.
43 In addition to lower usage of system resources, cntlm achieves higher
46 throughput on a given link. By caching authenticated connections, it
47 acts as an HTTP accelerator; This way, the 5-way auth handshake for
48 each connection is transparently eliminated, providing direct access
49 most of the time. NTLMAPS doesn't authenticate in parallel with the
50 request - instead, it first connects, sends a probe and disconnects. No
51 sooner than that it connects again and initiates NTLM handshake. Cntlm
52 also doesn't read the whole request including HTTP body into memory, in
53 fact, no traffic is generated except for the exchange of headers until
54 the client <-> server connection is fully negotiated. Only then are the
55 request and response bodies forwarded, directly between client and
56 server sockets. This way, cntlm avoids most of the TCP/IP overhead of
57 similar proxies. Along with the fact that cntlm is written in optimized
58 C, it achieves up to fifteen times faster responses. The slower the
59 line, the more impact cntlm has on download speeds.
60 An example of cntlm compared to NTLMAPS under the same conditions:
63 cntlm gave avg 76 kB/s with peak CPU usage of 0.3% whereas with NTLMAPS
64 it was avg 48 kB/s with peak CPU at 98% (Pentium M 1.8 GHz). The
65 extreme difference in resource usage is one of many important benefits
66 for laptop use. Peak memory consumption (several complex sites, 50
67 paralell connections/threads; values are in KiB):
68 VSZ RSS CMD
70 3204 1436 ./cntlm -f -c ./cntlm.conf -P pid
71 411604 6264 /usr/share/ntlmaps/main.py -c /etc/ntlmaps/server.cfg
72 Inherent part of the development is profiling and memory management
75 screening using Valgrind. The source distribution contains a file
76 called valgrind.txt, where you can see the report confirming zero
77 leaks, no access to unallocated memory, no usage of uninitialized data
78 - all tracked down to each CPU instruction emulated in Valgrind's vir‐
79 tual CPU during a typical production lifetime of the proxy.
80
83 Most options can be pre-set in a configuration file. Specifying an
84 option more than once is not an error, but cntlm ignores all occurences
85 except the last one. This does not apply to options like -L, each of
86 which creates a new instance of some feature. Cntlm can be built with a
87 hardcoded configuration file (e.g. /etc/cntlm.conf), which is always
88 loaded, if possible. See -c option on how to override some or all of
89 its settings.
90 Use -h to see available options with short description.
92 -A IP/mask (Allow)
95 Allow ACL rule. Together with -D (Deny) they are the two rules
96 allowed in ACL policy. It is more usual to have this in a con‐
97 figuration file, but Cntlm follows the premise that you can do
98 the same on the command-line as you can using the config file.
99 When Cntlm receives a connection request, it decides whether to
100 allow or deny it. All ACL rules are stored in a list in the same
101 order as specified. Cntlm then walks the list and the first
102 IP/mask rule that matches the request source address is applied.
103 The mask can be any number from 0 to 32, where 32 is the default
104 (that is exact IP match). This notation is also known as CIDR.
105 If you want to match everything, use 0/0 or an asterix. ACLs on
106 the command-line take precedence over those in the config file.
107 In such case, you will see info about that in the log (among the
108 list of unused options). There you can also see warnings about
109 possibly incorrect subnet spec, that's when the IP part has more
110 bits than you declare by mask (e.g. 10.20.30.40/24 should be
111 10.20.30.0/24).
112 -a NTLMv2 | NTLM2SR | NT | NTLM | LM (Auth)
115 Authentication type. NTLM(v2) comprises of one or two hashed
116 responses, NT and LM or NTLM2SR or NTv2 and LMv2, which are com‐
117 puted from the password hash. Each response uses a different
118 hashing algorithm; as new response types were invented, stronger
119 algorithms were used. When you first install cntlm, find the
120 strongest one which works for you (preferably using -M). Above
121 they are listed from strongest to weakest. Very old servers or
122 dedicated HW proxies might be unable to process anything but LM.
123 If none of those work, see compatibility flags option -F or sub‐
124 mit a Support Request.
125 IMPORTANT: Although NTLMv2 is not widely adopted (i.e.
127 enforced), it is supported on all Windows since NT 4.0 SP4.
128 That's for a very long time! I strongly suggest you use it to
129 protect your credentials on-line. You should also replace plain‐
130 text Password options with hashed Pass[NTLMv2|NT|LM] equiva‐
131 lents. NTLMv2 is the most and possibly the only secure authenti‐
132 cation of the NTLM family.
133 -B (NTLMToBasic)
136 This option enables "NTLM-to-basic", which allows you to use one
137 cntlm for multiple users. Please note that all security of NTLM
138 is lost this way. Basic auth uses just a simple encoding algo‐
139 rithm to "hide" your credentials and it is moderately easy to
140 sniff them.
141 IMPORTANT: HTTP protocol obviously has means to negotiate autho‐
143 rization before letting you through, but TCP/IP doesn't (i.e.
144 open port is open port). If you use NTLM-to-basic and DON'T
145 specify some username/password in the configuration file, you
146 are bound to loose tunneling features, because cntlm alone won't
147 know your credentials.
148 Because NTLM identification has at least three parts (username,
150 password, domain) and the basic authentication provides fields
151 for only two (username, password), you have to smuggle the
152 domain part somewhere. You can set the Domain config/cmd-line
153 parameter, which will then be used for all users, who don't
154 specify their domain as a part of the username. To do that and
155 override the global domain setting, use this instead of plain
156 username in the password dialog: "domain\username".
157 -c <filename>
160 Configuration file. Command-line options, if used, override its
161 single options or are added at the top of the list for multi
162 options (tunnels, parent proxies, etc) with the exception of
163 ACLs, which are completely overriden. Use /dev/null to disable
164 any config file.
165 -D IP/mask (Deny)
168 Deny ACL rule. See option -A above.
169 -d <domain> (Domain)
172 The domain or workgroup of the proxy account. This value can
173 also be specified as a part of the username with -u.
174 -F <flags> (Flags)
177 NTLM authentication flags. This option is rater delicate and I
178 do not recommend to change the default built-in values unless
179 you had no success with parent proxy auth and tried magic
180 autodetection (-M) and all possible values for the Auth option
181 (-a). Remember that each NT/LM hash combination requires differ‐
182 ent flags. This option is sort of a complete "manual override"
183 and you'll have to deal with it yourself.
184 -f Run in console as a foreground job, do not fork into background.
187 In this mode, all syslog messages will be echoed to the console
188 (on platforms which support syslog LOG_PERROR option). Though
189 cntlm is primarily designed as a classic UNIX daemon with sys‐
190 logd logging, it provides detailed verbose mode without detach‐
191 ing from the controlling terminal; see -v. In any case, all
192 error and diagnostic messages are always sent to the system log‐
193 ger.
194 -G <pattern> (ISAScannerAgent)
197 User-Agent matching (case insensitive) for trans-isa-scan plugin
198 (see -S for explanation). Positive match identifies requests
199 (applications) for which the plugin should be enabled without
200 considering the size of the download (see -S). You can use shell
201 wildcard characters, namely "*", "?" and "[]". If used without
202 -S or ISAScannerSize, the max_size_in_kb is internally set to
203 infinity, so the plugin will be active ONLY for selected User-
204 Agents, regardless of download size.
205 -g (Gateway)
208 Gateway mode, cntlm listens on all network interfaces. Default
209 is to bind just loopback. That way, only local processes can
210 connect to cntlm. In the gateway mode though, cntlm listens on
211 all interfaces and is accessible to other machines on the net‐
212 work. Please note that with this option the command-line order
213 matters when specifying proxy or tunnel local (listening) ports.
214 Those positioned before it will bind only loopback; those after
215 will be public.
216 IMPORTANT: All of the above applies only to local ports for
217 which you didn't specify any source address. If you did, cntlm
218 tries to bind the given port only on the specified interface (or
219 rather IP address).
220 -H Use this option to get hashes for password-less configuration.
223 In this mode, cntlm prints the results and exits. You can just
224 copy & paste right into the config file. You ought to use this
225 option with explicit -u and -d, because some hashes include the
226 username and domain name in the calculation. Do see -a for secu‐
227 rity recommendations.
228 -h Display help (available options with a short description) and
231 exit.
232 -I Interactive password prompt. Any password settings from the com‐
235 mand line or config file is ignored and a password prompt is
236 issued. Use this option only from shell.
237 -L [<saddr>:]<lport>:<rhost>:<rport> (Tunnel)
240 Tunnel specification. The syntax is the same as in OpenSSH's
241 local forwarding (-L), with a new optional prefix, saddr - the
242 source IP address to bind the lport to. Cntlm will listen for
243 incomming connections on the local port lport, forwarding every
244 new connection through the parent proxy to the rhost:rport
245 (authenticating on the go). This option can be used multiple
246 times for unlimited number of tunnels, with or without the saddr
247 option. See -g for the details concerning local port binding
248 when saddr is not used.
249 Please note that many corporate proxies do not allow connections
251 to ports other than 443 (https), but if you run your target ser‐
252 vice on this port, you should be safe. Connect to HTTPS is
253 "always" allowed, otherwise nobody would be able to browse
254 https:// sites. In any case, first try if you can establish a
255 connection through the tunnel, before you rely on it. This fea‐
256 ture does the same job as tools like corkscrew(1), but instead
257 of communicating over a terminal, cntlm keeps it TCP/IP.
258 -l [<saddr>:]<lport> (Listen)
261 Local port for the cntlm proxy service. Use the number you have
262 chosen here and the hostname of the machine running cntlm (pos‐
263 sibly localhost) as proxy settings in your browser and/or the
264 environment. Most applications (including console) support the
265 notion of proxy to connect to other hosts. On POSIX, set the
266 following variables to use e.g. wget(1) without any trouble
267 (fill in the actual address of cntlm):
268 $ export ftp_proxy=http://localhost:3128
270 $ export http_proxy=$ftp_proxy
271 $ export https_proxy=$ftp_proxy
272 You can choose to run the proxy service on more than one port,
274 in such case just use this option as many times as necessary.
275 But unlike tunnel specification, cntlm fails to start if it can‐
276 not bind all of the proxy service ports. Proxy service port can
277 also be bound selectively. Use saddr to pick source IP address
278 to bind the lport to. This allows you, for example, to run the
279 service on different ports for subnet A and B and make it invis‐
280 ible for subnet C. See -g for the details concerning local port
281 binding when saddr is not used.
282 -M <testurl>
285 Run magic NTLM dialect detection. In this mode, cntlm tries some
286 known working presets against your proxy. Probe requests are
287 made for the specified testurl, with the strongest hashes going
288 first. When finished, settings for the most secure setup are
289 printed. Although the detection will tell you which and how to
290 use Auth, Flags and password-hash options, you have to configure
291 at least your credentials and proxy address first. You can use
292 -I to enter your password interactively.
293 -O [<saddr>:]<port_number> (SOCKS5Proxy)
296 Enable SOCKS5 proxy and make it listen on local port port_number
297 (source IP spec is also possible, as with all options). By
298 default, there will be no restrictions as to who can use this
299 service. Some clients don't even support SOCKS5 authentication
300 (e.g. almost all browsers). If you wish to enforce authentica‐
301 tion, use -R or its equivalent option, SOCKS5User. As with port
302 tunneling, it is up to the parent proxy whether it will allow
303 connection to any requested host:port. This feature can be used
304 with tsocks(1) to make most TCP/IP applications go thru the
305 proxy rather than directly (only outgoing connections will work,
306 obviously). To make apps work without DNS server, it is impor‐
307 tant that they don't resolve themselves, but using SOCKS. E.g.
308 Firefox has this option available through URI "about:config",
309 key name network.proxy.socks_remote_dns, which must be set to
310 true. Proxy-unaware tsocksified apps, will have to be configured
311 using IP addresses to prevent them from DNS resolving.
312 -P <pidfile>
315 Create a PID file pidfile upon startup. If the specified file
316 exists, it is truncated and overwritten. This option is
317 intended for use with start-stop-daemon(8) and other servicing
318 mechanisms. Please note that the PID file is created AFTER the
319 process drops its privileges and forks. When the daemon finishes
320 cleanly, the file is removed.
321 -p <password> (Password, PassNT, ...)
324 Proxy account password. Cntlm deletes the password from the mem‐
325 ory, to make it invisible in /proc or with inspection tools like
326 ps(1), but the preferable way of specifying password is the con‐
327 figuration file. To that end, you can use Password option (for
328 plaintext, human readable format), or "encrypt" your password
329 via -H and then use PassNTLMv2, PassNT and/or PassLM.
330 -R <username>:<password> (SOCKS5User)
333 If SOCKS5 proxy is enabled, this option can make it accessible
334 only to those who have been authorized. It can be used several
335 times, to create a whole list of accounts (allowed user:pass
336 combinations).
337 -S <max_size_in_kb> (ISAScannerSize)
340 Enables the plugin for transparent handling of the dreaded ISA
341 AV scanner, which returns an interactive HTTP page (displaying
342 the scanning progress) instead of the file/data you've
343 requested, every time it feels like scanning the contents. This
344 presumptuous behavior breaks every automated downloader, updater
345 and basically EVERY application relying on downloads (e.g. wget,
346 apt-get).
347 The parameter max_size_in_kb allows you to choose maximum down‐
349 load size you wish to handle by the plugin (see below why you
350 might want that). If the file size is bigger than this, cntlm
351 forwards you the interactive page, effectively disabling the
352 plugin for that download. Zero means no limit. Use -G/ISAScan‐
353 nerAgent to identify applications for which max_size_in_kb
354 should be ignored (forcing the plugin). It works by matching
355 User-Agent header and is necessary for e.g. wget, apt-get and
356 yum, which would fail if the response is some HTTP page instead
357 of requested data.
358 How it works: the client asks for a file, cntlm detects ISA's
360 bullshit response and waits for the secret link to ISA's cache,
361 which comes no sooner than the file is downloaded and scanned by
362 ISA. Only then can cntlm make the second request for the real
363 file and forward it along with correct headers to the client.
364 The client doesn't timeout while waiting for it, b/c cntlm is
365 periodically sending an extra "keepalive" header, but the user
366 might get nervous not seeing the progress bar move. It's of
367 course purely psychological matter, there's no difference if
368 cntlm or your browser requests the scanned file - you must wait
369 for ISA to do it's job and download then. You just expect to see
370 some progress indicator move, which is all what the ISA's page
371 does: it shows HTML countdown.
372 If the plugin cannot parse the interactive page for some reason
374 (unknown formatting, etc.), it quits and the page is forwarded
375 to you - it's never "lost".
376 The keepalive header is called ISA-Scanner and shows ISA's
378 progress, e.g.:
379 HTTP/1.1 200 OK
381 ISA-Scanner: 1000 of 10000
382 ISA-Scanner: 2000 of 10000
383 ...
384 -r "<name>: <value>" (Header)
387 Header substitution. Every client's request will be processed
388 and any headers defined using -r or in the configuration file
389 will be added to it. In case the header is already present, its
390 value will be replaced.
391 -s Serializes all requests by not using concurrent threads for
394 proxy (tunneling still works in parallel). This has a horrible
395 impact on performance and is available only for debugging pur‐
396 poses. When used with -v, it yields nice sequential debug log,
397 where requests take turns.
398 -T <filename>
401 Used in combination with -v to save the debug output into a
402 trace file. It should be placed as the first parameter on the
403 command line. To prevent data loss, it never overwrites an
404 existing file. You have to pick a unique name or manually delete
405 the old file.
406 -U <uid>
409 When executed as root, do the stuff that needs such permissions
410 (read config, bind ports, etc.) and then immediately drop privi‐
411 leges and change to uid. This parameter can be either number or
412 system username. If you use a number, both uid and gid of the
413 process will be set to this value; if you specify a username,
414 uid and gid will be set according to that user's uid and primary
415 gid as defined in /etc/passwd. You should use the latter, possi‐
416 bly using a dedicated cntlm account. As with any daemon, you are
417 strongly advised to run cntlm under a non-privileged account.
418 -u <user>[@<domain>] (Username)
421 Proxy account/user name. Domain can be be entered as well.
422 -v Print debugging information. Automatically enables (-f).
425 -w <workstation> (Workstation)
428 Workstation NetBIOS name. Do not use full domain name (FQDN)
429 here. Just the first part. If not specified, cntlm tries to get
430 the system hostname and if that fails, uses "cntlm" - it's
431 because some proxies require this field non-empty.
432
435 Configuration file has the same syntax as OpenSSH ssh_config. It com‐
436 prises of whitespace delimited keywords and values. Comment begins with
437 a hash '#' and can begin anywhere in the file. Everything after the
438 hash up until the EOL is a comment. Values can contain any characters,
439 including whitespace. Do not quote anything. For detailed explanation
440 of keywords, see appropriate command-line options. Following keywords
441 are available:
442 Allow <IP>[/<mask>]
445 ACL allow rule, see -A.
446 Auth NTLMv2 | NTLM2SR | NT | NTLM | LM
449 Select any possible combination of NTLM hashes using a single
450 parameter.
451 Deny <IP>[/<mask>]
454 ACL deny rule, see -A.
455 Domain <domain_name>
458 Proxy account domain/workgroup name.
459 Flags <flags>
462 NTLM authentication flags. See -F for details.
463 Gateway yes|no
466 Gateway mode. In the configuration file, order doesn't matter.
467 Gateway mode applies the same to all tunnels.
468 Header <headername: value>
471 Header substitution. See -r for details and remember, no quot‐
472 ing.
473 ISAScannerAgent <pattern>
476 Wildcard-enabled (*, ?, []) case insensitive User-Agent string
477 matching for the trans-isa-plugin. If you don't define ISAScan‐
478 nerSize, it is internally set to infinity, i.e. disabling the
479 plugin for all downloads except those agent-matched ones. See
480 -G.
481 ISAScannerSize <max_size_in_kb>
484 Enable trans-isa-scan plugin. See -S for more.
485 Listen [<saddr>:]<port_number>
488 Local port number for the cntlm's proxy service. See -l for
489 more.
490 Password <password>
493 Proxy account password.
494 PassNTLMv2, PassNT, PassLM <password>
497 Hashes of the proxy account password (see -H and -a). When you
498 want to use hashes in the config (instead of plaintext pass‐
499 word), each Auth settings requires different options:
500 Settings | Requires
502 -------------+-----------------
503 Auth NTLMv2 | PassNTLMv2
504 Auth NTLM2SR | PassNT
505 Auth NT | PassNT
506 Auth NTLM | PassNT + PassLM
507 Auth LM | PassLM
508 Proxy <host:port>
511 Parent proxy, which requires authentication. The same as proxy
512 on the command-line, can be used more than once to specify
513 unlimited number of proxies. Should one proxy fail, cntlm auto‐
514 matically moves on to the next one. The connect request fails
515 only if the whole list of proxies is scanned and (for each
516 request) and found to be invalid. Command-line takes precedence
517 over the configuration file.
518 SOCKS5Proxy [<saddr>:]<lport>
521 Enable SOCKS5 proxy. See -O for more.
522 SOCKS5User <username>:<password>
525 Create a new SOCKS5 proxy account. See -R for more.
526 NTLMToBasic yes|no
529 Enable/disable NTLM-to-basic authenticatoin. See -B for more.
530 Tunnel [<saddr>:]<lport>:<rhost>:<rport>
533 Tunnel specification. See -L for more.
534 Username
537 Proxy account name, without the possibility to include domain
538 name ('at' sign is interpreted literally).
539 Workstation <hostname>
542 The hostname of your workstation.
543
546 The optional location of the configuration file is defined in the Make‐
547 file, with the default for 1) deb/rpm package, 2) traditional "make;
548 make install" and 3) Windows installer being:
549 1) /etc/cntlm.conf
551 2) /usr/local/etc/cntlm.conf
552 3) %PROGRAMFILES%\Cntlm\cntlm.ini
553
556 Cntlm has been successfully compiled and tested on both little and big
557 endian machines (Linux/i386 and AIX/PowerPC). For compilation details,
558 see README in the source distribution. Porting to any POSIX conforming
559 OS shouldn't be more than a matter of the Makefile rearrangement. Cntlm
560 uses strictly POSIX.1-2001 interfaces with ISO C99 libc (snprintf(3)),
561 it is also compliant with SUSv3. Since version 0.33, cntlm supports
562 Windows using POSIX emulation layer Cygwin.
563
566 In the much needed NTLM-proxy departement, cntlm aims to be a drop-in
567 replacement for NTLMAPS. But please note that NTLM WWW auth (that is
568 auth to HTTP servers), when it is running without any parent proxy as a
569 standalone proxy server in itself, won't probaly be implemented ever.
570 Even though the tasks share common NTLM authentication, they are dif‐
571 ferent things. Also, I've never seen any access-protected HTTP server
572 requiring solely NTLM without any alternative. Such a narrow-spectrum
573 tool can be written in Perl in a few minutes. I strive to keep the code
574 of cntlm simple and efficient.
575
578 This software is still BETA, so there are probably many bugs for you to
579 uncloak even though I'm testing every new piece of code AMAP and use
580 cntlm daily. I'll be happy to fix all of them, but if you can manage,
581 patches would be better. ;)
582 To report a bug, enable the debug output, save it to a file and submit
584 on-line along with a detailed description of the problem and how to
585 reproduce it. The link can be found on the homepage.
586 To generate the debug tracefile correctly, first run cntlm from the
588 shell (command line) and make sure you can reproduce the bug. When you
589 will have verfied that, stop cntlm (hit Ctrl-C) and insert the follow‐
590 ing parameters at the beginning of the command line, preserving their
591 order. Example:
592 cntlm[.exe] -T cntlmtrace.log -v -s ... the rest ...
594
597 Written by David Kubicek <dave (o) awk.cz>
598 Homepage: http://cntlm.sourceforge.net/
599
602 Copyright © 2007 David Kubicek
603 Cntlm uses DES, MD4, MD5 and HMAC-MD5 routines from gnulib and Base64
604 routines from mutt(1).
605cntlm 0.35 Nov 2007 CNTLM(1)