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/NTLM SR/NTLMv2 authenticating HTTP proxy. It stands
17 between your applications and the corporate proxy, adding NTLM authen‐
18 tication on-the-fly. You can specify several "parent" proxies and Cntlm
19 will try one after another until one works. All auth'd connections are
20 cached and reused to achieve high efficiency. Just point your apps
21 proxy settings at Cntlm, fill in cntlm.conf (cntlm.ini) and you're
22 ready to do. This is useful on Windows, but essential for non-Microsoft
23 OS's. Proxy IP addresses can be specified via CLI (host1:port1 to
24 hostN:portN) or the configuration file.
25 Another option is to have cntlm authenticate your local web connections
27 without any parent proxies. It can work in a stand-alone mode, just
28 like Squid or ISA. By default, all requests are forwarded to parent
29 proxies, but the user can set a "NoProxy" list, a list of URL matching
30 wild-card patterns, that route between direct and forward modes. Cntlm
31 can also recognize when all your corporate proxies are unavailable and
32 switch to stand-alone mode automatically (and then back again). Aside
33 from WWW and PROXY authentication, cntlm provides a useful feature
34 enabling users migrate their laptops between work and home without
35 changing proxy settings in their applications (using cntlm all the
36 time). Cntlm also integrates transparent TCP/IP port forwarding (tun‐
37 neling). Each tunnel opens a new listening socket on local machine and
38 and forwards all connections to the target host behind the parent
39 proxy. Instead of these SSH-like tunnels, user can also choose a lim‐
40 ited SOCKS5 interface.
41 Core cntlm function had been similar to the late NTLMAPS, but today,
44 cntlm has evolved way beyond anything any other application of this
45 type can offer. The feature list below speaks for itself. Cntlm has
46 many security/privacy features like NTLMv2 support and password protec‐
47 tion - it is possible to substitute password hashes (which can be
48 obtained using -H) in place of the actual password or to enter the
49 password interactively (on start-up or via "basic" HTTP auth transla‐
50 tion). If plaintext password is used, it is automatically hashed during
51 the startup and all traces of it are removed from the process memory.
52 In addition to minimal use of system resources, cntlm achieves higher
55 throughput on a given link. By caching authenticated connections, it
56 acts as an HTTP accelerator; This way, the 5-way auth handshake for
57 each connection is transparently eliminated, providing immediate access
58 most of the time. Cntlm never caches a request/reply body in memory, in
59 fact, no traffic is generated except for the exchange of auth headers
60 until the client <-> server connection is fully negotiated. Only then
61 real data transfer takes place. Cntlm is written in optimized C and
62 easily achieves fifteen times faster responses than others.
63 An example of cntlm compared to NTLMAPS: cntlm gave avg 76 kB/s with
66 peak CPU usage of 0.3% whereas with NTLMAPS it was avg 48 kB/s with
67 peak CPU at 98% (Pentium M 1.8 GHz). The extreme difference in resource
68 usage is one of many important benefits for laptop use. Peak memory
69 consumption (several complex sites, 50 paralell connections/threads;
70 values are in KiB):
71 VSZ RSS CMD
73 3204 1436 ./cntlm -f -c ./cntlm.conf -P pid
74 411604 6264 /usr/share/ntlmaps/main.py -c /etc/ntlmaps/server.cfg
75 Inherent part of the development is profiling and memory management
78 screening using Valgrind. The source distribution contains a file
79 called valgrind.txt, where you can see the report confirming zero
80 leaks, no access to unallocated memory, no usage of uninitialized data
81 - all traced down to each instruction emulated in Valgrind's virtual
82 CPU during a typical production lifetime of the proxy.
83
86 Most options can be pre-set in a configuration file. Specifying an
87 option more than once is not an error, but cntlm ignores all occurences
88 except the last one. This does not apply to options like -L, each of
89 which creates a new instance of some feature. Cntlm can be built with a
90 hardcoded configuration file (e.g. /etc/cntlm.conf), which is always
91 loaded, if possible. See -c option on how to override some or all of
92 its settings.
93 Use -h to see available options with short description.
95 -A IP/mask (Allow)
98 Allow ACL rule. Together with -D (Deny) they are the two rules
99 allowed in ACL policy. It is more usual to have this in a con‐
100 figuration file, but Cntlm follows the premise that you can do
101 the same on the command-line as you can using the config file.
102 When Cntlm receives a connection request, it decides whether to
103 allow or deny it. All ACL rules are stored in a list in the same
104 order as specified. Cntlm then walks the list and the first
105 IP/mask rule that matches the request source address is applied.
106 The mask can be any number from 0 to 32, where 32 is the default
107 (that is exact IP match). This notation is also known as CIDR.
108 If you want to match everything, use 0/0 or an asterix. ACLs on
109 the command-line take precedence over those in the config file.
110 In such case, you will see info about that in the log (among the
111 list of unused options). There you can also see warnings about
112 possibly incorrect subnet spec, that's when the IP part has more
113 bits than you declare by mask (e.g. 10.20.30.40/24 should be
114 10.20.30.0/24).
115 -a NTLMv2 | NTLM2SR | NT | NTLM | LM (Auth)
118 Authentication type. NTLM(v2) comprises of one or two hashed
119 responses, NT and LM or NTLM2SR or NTv2 and LMv2, which are com‐
120 puted from the password hash. Each response uses a different
121 hashing algorithm; as new response types were invented, stronger
122 algorithms were used. When you first install cntlm, find the
123 strongest one which works for you (preferably using -M). Above
124 they are listed from strongest to weakest. Very old servers or
125 dedicated HW proxies might be unable to process anything but LM.
126 If none of those work, see compatibility flags option -F or sub‐
127 mit a Support Request.
128 IMPORTANT: Although NTLMv2 is not widely adopted (i.e.
130 enforced), it is supported on all Windows since NT 4.0 SP4.
131 That's for a very long time! I strongly suggest you use it to
132 protect your credentials on-line. You should also replace plain‐
133 text Password options with hashed Pass[NTLMv2|NT|LM] equiva‐
134 lents. NTLMv2 is the most and possibly the only secure authenti‐
135 cation of the NTLM family.
136 -B (NTLMToBasic)
139 This option enables "NTLM-to-basic", which allows you to use one
140 cntlm for multiple users. Please note that all security of NTLM
141 is lost this way. Basic auth uses just a simple encoding algo‐
142 rithm to "hide" your credentials and it is moderately easy to
143 sniff them.
144 IMPORTANT: HTTP protocol obviously has means to negotiate autho‐
146 rization before letting you through, but TCP/IP doesn't (i.e.
147 open port is open port). If you use NTLM-to-basic and DON'T
148 specify some username/password in the configuration file, you
149 are bound to loose tunneling features, because cntlm alone won't
150 know your credentials.
151 Because NTLM identification has at least three parts (username,
153 password, domain) and the basic authentication provides fields
154 for only two (username, password), you have to smuggle the
155 domain part somewhere. You can set the Domain config/cmd-line
156 parameter, which will then be used for all users, who don't
157 specify their domain as a part of the username. To do that and
158 override the global domain setting, use this instead of plain
159 username in the password dialog: "domain\username".
160 -c <filename>
163 Configuration file. Command-line options, if used, override its
164 single options or are added at the top of the list for multi
165 options (tunnels, parent proxies, etc) with the exception of
166 ACLs, which are completely overriden. Use /dev/null to disable
167 any config file.
168 -D IP/mask (Deny)
171 Deny ACL rule. See option -A above.
172 -d <domain> (Domain)
175 The domain or workgroup of the proxy account. This value can
176 also be specified as a part of the username with -u.
177 -F <flags> (Flags)
180 NTLM authentication flags. This option is rater delicate and I
181 do not recommend to change the default built-in values unless
182 you had no success with parent proxy auth and tried magic
183 autodetection (-M) and all possible values for the Auth option
184 (-a). Remember that each NT/LM hash combination requires differ‐
185 ent flags. This option is sort of a complete "manual override"
186 and you'll have to deal with it yourself.
187 -f Run in console as a foreground job, do not fork into background.
190 In this mode, all syslog messages will be echoed to the console
191 (on platforms which support syslog LOG_PERROR option). Though
192 cntlm is primarily designed as a classic UNIX daemon with sys‐
193 logd logging, it provides detailed verbose mode without detach‐
194 ing from the controlling terminal; see -v. In any case, all
195 error and diagnostic messages are always sent to the system log‐
196 ger.
197 -G <pattern> (ISAScannerAgent)
200 User-Agent matching (case insensitive) for trans-isa-scan plugin
201 (see -S for explanation). Positive match identifies requests
202 (applications) for which the plugin should be enabled without
203 considering the size of the download (see -S). You can use shell
204 wildcard characters, namely "*", "?" and "[]". If used without
205 -S or ISAScannerSize, the max_size_in_kb is internally set to
206 infinity, so the plugin will be active ONLY for selected User-
207 Agents, regardless of download size.
208 -g (Gateway)
211 Gateway mode, cntlm listens on all network interfaces. Default
212 is to bind just loopback. That way, only local processes can
213 connect to cntlm. In the gateway mode though, cntlm listens on
214 all interfaces and is accessible to other machines on the net‐
215 work. Please note that with this option the command-line order
216 matters when specifying proxy or tunnel local (listening) ports.
217 Those positioned before it will bind only loopback; those after
218 will be public.
219 IMPORTANT: All of the above applies only to local ports for
220 which you didn't specify any source address. If you did, cntlm
221 tries to bind the given port only on the specified interface (or
222 rather IP address).
223 -H Use this option to get hashes for password-less configuration.
226 In this mode, cntlm prints the results and exits. You can just
227 copy & paste right into the config file. You ought to use this
228 option with explicit -u and -d, because some hashes include the
229 username and domain name in the calculation. Do see -a for secu‐
230 rity recommendations.
231 -h Display help (available options with a short description) and
234 exit.
235 -I Interactive password prompt. Any password settings from the com‐
238 mand line or config file is ignored and a password prompt is
239 issued. Use this option only from shell.
240 -L [<saddr>:]<lport>:<rhost>:<rport> (Tunnel)
243 Tunnel definition. The syntax is the same as in OpenSSH's local
244 forwarding (-L), with a new optional prefix, saddr - the source
245 IP address to bind the lport to. Cntlm will listen for incomming
246 connections on the local port lport, forwarding every new con‐
247 nection through the parent proxy to the rhost:rport (authenti‐
248 cating on the go). This option can be used multiple times for
249 unlimited number of tunnels, with or without the saddr option.
250 See -g for the details concerning local port binding when saddr
251 is not used.
252 Please note that many corporate proxies do not allow connections
254 to ports other than 443 (https), but if you run your target ser‐
255 vice on this port, you should be safe. Connect to HTTPS is
256 "always" allowed, otherwise nobody would be able to browse
257 https:// sites. In any case, first try if you can establish a
258 connection through the tunnel, before you rely on it. This fea‐
259 ture does the same job as tools like corkscrew(1), but instead
260 of communicating over a terminal, cntlm keeps it TCP/IP.
261 -l [<saddr>:]<lport> (Listen)
264 Local port for the cntlm proxy service. Use the number you have
265 chosen here and the hostname of the machine running cntlm (pos‐
266 sibly localhost) as proxy settings in your browser and/or the
267 environment. Most applications (including console) support the
268 notion of proxy to connect to other hosts. On POSIX, set the
269 following variables to use e.g. wget(1) without any trouble
270 (fill in the actual address of cntlm):
271 $ export ftp_proxy=http://localhost:3128
273 $ export http_proxy=$ftp_proxy
274 $ export https_proxy=$ftp_proxy
275 You can choose to run the proxy service on more than one port,
277 in such case just use this option as many times as necessary.
278 But unlike tunnel definition, cntlm fails to start if it cannot
279 bind all of the proxy service ports. Proxy service port can also
280 be bound selectively. Use saddr to pick source IP address to
281 bind the lport to. This allows you, for example, to run the ser‐
282 vice on different ports for subnet A and B and make it invisible
283 for subnet C. See -g for the details concerning local port bind‐
284 ing when saddr is not used.
285 -M <testurl>
288 Run magic NTLM dialect detection. In this mode, cntlm tries some
289 known working presets against your proxy. Probe requests are
290 made for the specified testurl, with the strongest hashes going
291 first. When finished, settings for the most secure setup are
292 printed. Although the detection will tell you which and how to
293 use Auth, Flags and password-hash options, you have to configure
294 at least your credentials and proxy address first. You can use
295 -I to enter your password interactively.
296 -N <pattern1>[,<patternN] (NoProxy)
299 Avoid parent proxy for these host names. All matching URL's will
300 be proxied directly by cntlm as a stand-alone proxy. Cntlm sup‐
301 ports WWW authentication in this mode, thus allowing you to
302 access local intranet sites with corporate NTLM authentication.
303 Hopefully, you won't need that virtualized MSIE any more. :)
304 -O [<saddr>:]<port_number> (SOCKS5Proxy)
307 Enable SOCKS5 proxy and make it listen on local port port_number
308 (source IP spec is also possible, as with all options). By
309 default, there will be no restrictions as to who can use this
310 service. Some clients don't even support SOCKS5 authentication
311 (e.g. almost all browsers). If you wish to enforce authentica‐
312 tion, use -R or its equivalent option, SOCKS5User. As with port
313 tunneling, it is up to the parent proxy whether it will allow
314 connection to any requested host:port. This feature can be used
315 with tsocks(1) to make most TCP/IP applications go thru the
316 proxy rather than directly (only outgoing connections will work,
317 obviously). To make apps work without DNS server, it is impor‐
318 tant that they don't resolve themselves, but using SOCKS. E.g.
319 Firefox has this option available through URI "about:config",
320 key name network.proxy.socks_remote_dns, which must be set to
321 true. Proxy-unaware tsocksified apps, will have to be configured
322 using IP addresses to prevent them from DNS resolving.
323 -P <pidfile>
326 Create a PID file pidfile upon startup. If the specified file
327 exists, it is truncated and overwritten. This option is
328 intended for use with start-stop-daemon(8) and other servicing
329 mechanisms. Please note that the PID file is created AFTER the
330 process drops its privileges and forks. When the daemon finishes
331 cleanly, the file is removed.
332 -p <password> (Password, PassNT, ...)
335 Proxy account password. Cntlm deletes the password from the mem‐
336 ory, to make it invisible in /proc or with inspection tools like
337 ps(1), but the preferable way of setting password is the config‐
338 uration file. To that end, you can use Password option (for
339 plaintext, human readable format), or "encrypt" your password
340 via -H and then use PassNTLMv2, PassNT and/or PassLM.
341 -R <username>:<password> (SOCKS5User)
344 If SOCKS5 proxy is enabled, this option can make it accessible
345 only to those who have been authorized. It can be used several
346 times, to create a whole list of accounts (allowed user:pass
347 combinations).
348 -S <max_size_in_kb> (ISAScannerSize)
351 Enables the plugin for transparent handling of the dreaded ISA
352 AV scanner, which returns an interactive HTTP page (displaying
353 the scanning progress) instead of the file/data you've
354 requested, every time it feels like scanning the contents. This
355 presumptuous behavior breaks every automated downloader, updater
356 and basically EVERY application relying on downloads (e.g. wget,
357 apt-get).
358 The parameter max_size_in_kb allows you to choose maximum down‐
360 load size you wish to handle by the plugin (see below why you
361 might want that). If the file size is bigger than this, cntlm
362 forwards you the interactive page, effectively disabling the
363 plugin for that download. Zero means no limit. Use -G/ISAScan‐
364 nerAgent to identify applications for which max_size_in_kb
365 should be ignored (forcing the plugin). It works by matching
366 User-Agent header and is necessary for e.g. wget, apt-get and
367 yum, which would fail if the response is some HTTP page instead
368 of requested data.
369 How it works: the client asks for a file, cntlm detects ISA's
371 bullshit response and waits for the secret link to ISA's cache,
372 which comes no sooner than the file is downloaded and scanned by
373 ISA. Only then can cntlm make the second request for the real
374 file and forward it along with correct headers to the client.
375 The client doesn't timeout while waiting for it, b/c cntlm is
376 periodically sending an extra "keepalive" header, but the user
377 might get nervous not seeing the progress bar move. It's of
378 course purely psychological matter, there's no difference if
379 cntlm or your browser requests the scanned file - you must wait
380 for ISA to do it's job and download then. You just expect to see
381 some progress indicator move, which is all what the ISA's page
382 does: it shows HTML countdown.
383 If the plugin cannot parse the interactive page for some reason
385 (unknown formatting, etc.), it quits and the page is forwarded
386 to you - it's never "lost".
387 The keepalive header is called ISA-Scanner and shows ISA's
389 progress, e.g.:
390 HTTP/1.1 200 OK
392 ISA-Scanner: 1000 of 10000
393 ISA-Scanner: 2000 of 10000
394 ...
395 -r "<name>: <value>" (Header)
398 Header substitution. Every client's request will be processed
399 and any headers defined using -r or in the configuration file
400 will be added to it. In case the header is already present, its
401 value will be replaced.
402 -s Serializes all requests by not using concurrent threads for
405 proxy (tunneling still works in parallel). This has a horrible
406 impact on performance and is available only for debugging pur‐
407 poses. When used with -v, it yields nice sequential debug log,
408 where requests take turns.
409 -T <filename>
412 Used in combination with -v to save the debug output into a
413 trace file. It should be placed as the first parameter on the
414 command line. To prevent data loss, it never overwrites an
415 existing file. You have to pick a unique name or manually delete
416 the old file.
417 -U <uid>
420 When executed as root, do the stuff that needs such permissions
421 (read config, bind ports, etc.) and then immediately drop privi‐
422 leges and change to uid. This parameter can be either number or
423 system username. If you use a number, both uid and gid of the
424 process will be set to this value; if you specify a username,
425 uid and gid will be set according to that user's uid and primary
426 gid as defined in /etc/passwd. You should use the latter, possi‐
427 bly using a dedicated cntlm account. As with any daemon, you are
428 strongly advised to run cntlm under a non-privileged account.
429 -u <user>[@<domain>] (Username)
432 Proxy account/user name. Domain can be be entered as well.
433 -v Print debugging information. Automatically enables (-f).
436 -w <workstation> (Workstation)
439 Workstation NetBIOS name. Do not use full qualified domain name
440 (FQDN) here. Just the first part. If not specified, cntlm tries
441 to get the system hostname and if that fails, uses "cntlm" -
442 it's because some proxies require this field non-empty.
443
446 Configuration file is basically an INI file, except there are no "="
447 between keys and values. It comprises of whitespace delimited keyword
448 and value pairs. Apart from that, there are sections as well, they have
449 the usual "[section_name]" syntax. Comment begins with a hash "#" or a
450 semicolon ";" and can be anywhere in the file. Everything after the
451 mark up until EOL is a comment. Values can contain any characters,
452 including whitespace. You can use double quotes around the value to
453 set a string containing special characters like spaces, pound signs,
454 etc. No escape sequences are allowed in quoted strings.
455 There are two types of keywords, local and global. Local options spec‐
457 ify authentication details per domain (or location). Global keywords
458 apply to all sections and proxies. They should be placed before all
459 sections, but it's not necessary. They are: Allow, Deny, Gateway, Lis‐
460 ten, SOCKS5Proxy, SOCKS5User, NTLMToBasic, Tunnel.
461 All available keywords are listed here, full descriptions are in the
463 OPTIONS section:
464 Allow <IP>[/<mask>]
467 ACL allow rule, see -A.
468 Auth NTLMv2 | NTLM2SR | NT | NTLM | LM
471 Select any possible combination of NTLM hashes using a single
472 parameter.
473 Deny <IP>[/<mask>]
476 ACL deny rule, see -A.
477 Domain <domain_name>
480 Proxy account domain/workgroup name.
481 Flags <flags>
484 NTLM authentication flags. See -F for details.
485 Gateway yes|no
488 Gateway mode. In the configuration file, order doesn't matter.
489 Gateway mode applies the same to all tunnels.
490 Header <headername: value>
493 Header substitution. See -r for details and remember, no quot‐
494 ing.
495 ISAScannerAgent <pattern>
498 Wildcard-enabled (*, ?, []) case insensitive User-Agent string
499 matching for the trans-isa-plugin. If you don't define ISAScan‐
500 nerSize, it is internally set to infinity, i.e. disabling the
501 plugin for all downloads except those agent-matched ones. See
502 -G.
503 ISAScannerSize <max_size_in_kb>
506 Enable trans-isa-scan plugin. See -S for more.
507 Listen [<saddr>:]<port_number>
510 Local port number for the cntlm's proxy service. See -l for
511 more.
512 Password <password>
515 Proxy account password. As with any other option, the value
516 (password) can be enclosed in double quotes (") in case it con‐
517 tains special characters like spaces, pound signs, etc.
518 PassNTLMv2, PassNT, PassLM <password>
521 Hashes of the proxy account password (see -H and -a). When you
522 want to use hashes in the config (instead of plaintext pass‐
523 word), each Auth settings requires different options:
524 Settings | Requires
526 -------------+-----------------
527 Auth NTLMv2 | PassNTLMv2
528 Auth NTLM2SR | PassNT
529 Auth NT | PassNT
530 Auth NTLM | PassNT + PassLM
531 Auth LM | PassLM
532 Proxy <host:port>
535 Parent proxy, which requires authentication. The same as proxy
536 on the command-line, can be used more than once to specify an
537 arbitrary number of proxies. Should one proxy fail, cntlm auto‐
538 matically moves on to the next one. The connect request fails
539 only if the whole list of proxies is scanned and (for each
540 request) and found to be invalid. Command-line takes precedence
541 over the configuration file.
542 NoProxy <pattern1>, <pattern2>, ...
545 Avoid parent proxy for these host names. All matching URL's will
546 be proxied directly by cntlm as a stand-alone proxy. Cntlm sup‐
547 ports WWW authentication in this mode, thus allowing you to
548 access local intranet sites with corporate NTLM authentication.
549 Hopefully, you won't need that virtualized MSIE any more. :) See
550 -N for more.
551 SOCKS5Proxy [<saddr>:]<lport>
554 Enable SOCKS5 proxy. See -O for more.
555 SOCKS5User <username>:<password>
558 Create a new SOCKS5 proxy account. See -R for more.
559 NTLMToBasic yes|no
562 Enable/disable NTLM-to-basic authenticatoin. See -B for more.
563 Tunnel [<saddr>:]<lport>:<rhost>:<rport>
566 Tunnel definition. See -L for more.
567 Username
570 Proxy account name, without the possibility to include domain
571 name ('at' sign is interpreted literally).
572 Workstation <hostname>
575 The hostname of your workstation.
576
579 The optional location of the configuration file is defined in the Make‐
580 file, with the default for 1) deb/rpm package, 2) traditional "make;
581 make install" and 3) Windows installer, respectively, being:
582 1) /etc/cntlm.conf
584 2) /usr/local/etc/cntlm.conf
585 3) %PROGRAMFILES%\Cntlm\cntlm.ini
586
589 Cntlm is being used on many platforms, little and big endian machines,
590 so users should not have any problems with compilation. Nowadays, cntlm
591 is a standard tool in most Linux distributions and there are various
592 repositories for other UNIX-like systems. Personally, I release Debian
593 Linux (deb), RedHat Linux (rpm) and Windows (exe) binaries, but most
594 people get cntlm from their OS distributor.
595 For compilation details, see README in the source distribution. Porting
597 to any POSIX conforming OS shouldn't be more than a matter of a Make‐
598 file rearrangement. Cntlm uses strictly POSIX.1-2001 interfaces with
599 ISO C99 libc and is also compliant with SUSv3. Since version 0.33,
600 cntlm supports Windows using a POSIX emulation layer called Cygwin.
601
604 To report a bug, enable the debug output, save it to a file and submit
605 on-line along with a detailed description of the problem and how to
606 reproduce it. Visit the home page for more.
607 cntlm -T cntlmtrace.log -v -s ... the rest ...
609
612 Written by David Kubicek <dave (o) awk.cz>
613 Homepage: http://cntlm.sourceforge.net/
614
617 Copyright © 2007-2010 David Kubicek
618 Cntlm uses DES, MD4, MD5 and HMAC-MD5 routines from gnulib and Base64
619 routines from mutt(1).
620cntlm 0.90 Nov 2010 CNTLM(1)