Man Linux: Main Page and Category List


       cntlm   -  authenticating  HTTP(S)  proxy  with  TCP/IP  tunneling  and


       cntlm [ -AaBcDdFfgHhILlMPprSsTUuvw ] [ host1 port1 | host1:port1 ]  ...
       hostN portN


       Cntlm is an NTLM/NTLMv2 authenticating HTTP proxy. It takes the address
       of your proxy or proxies (host1..N and port1..N) and opens a  listening
       socket,  forwarding  each  request  to  the  parent  proxy (moving in a
       circular list if the active parent stops working).  Along  the  way,  a
       connection  to  the  parent  is  created  anew and authenticated or, if
       available, previously cached connection is  reused  to  achieve  higher
       efficiency  and  faster  responses.   When  the  chain is set up, cntlm
       should be used as a proxy in your applications. Cntlm  also  integrates
       transparent  TCP/IP  port  forwarding  (tunneling)  through  the parent
       (incl. authentication). Each tunnel opens a new listening socket on the
       defined  local port and forwards all connections to the given host:port
       behind the secondary proxy.  Manual page explains how  to  setup  cntlm
       properly using configuration file or command-line arguments.

       Cntlm  works  similarly to NTLMAPS, plus full NTLM support, a bucket of
       new features and none of its shortcomings and inefficiencies.  It  adds
       support  for  real  keep-alive  (on  both  sides)  and  it  caches  all
       authenticated connections for reuse in subsequent requests. It  can  be
       restarted  without  TIME_WAIT  delay,  uses  just  a fraction of memory
       compared to NTLMAPS and by orders of magnitude less CPU. Each thread is
       completely  independent  and  one  cannot block another. Cntlm has many
       security/privacy features like NTLMv2 support and password protection -
       it  is  possible  to  substitute password hashes (which can be obtained
       using -H)  for  the  actual  password  or   to   enter   the   password
       interactively.  If  plaintext  password  is  used,  it is automatically
       hashed during the startup and all  its  traces  are  removed  from  the
       process memory.

       In  addition  to lower usage of system resources, cntlm achieves higher
       throughput on a given link. By caching  authenticated  connections,  it
       acts  as  an  HTTP  accelerator; This way, the 5-way auth handshake for
       each connection is transparently eliminated,  providing  direct  access
       most  of  the  time.  NTLMAPS doesn’t authenticate in parallel with the
       request - instead, it first connects, sends a probe and disconnects. No
       sooner  than that it connects again and initiates NTLM handshake. Cntlm
       also doesn’t read the whole request including HTTP body into memory, in
       fact,  no traffic is generated except for the exchange of headers until
       the client <-> server connection is fully negotiated. Only then are the
       request  and  response  bodies  forwarded,  directly between client and
       server sockets. This way, cntlm avoids most of the TCP/IP  overhead  of
       similar proxies. Along with the fact that cntlm is written in optimized
       C, it achieves up to fifteen times faster  responses.  The  slower  the
       line, the more impact cntlm has on download speeds.

       An  example  of  cntlm  compared  to NTLMAPS under the same conditions:
       cntlm gave avg 76 kB/s with peak CPU usage of 0.3% whereas with NTLMAPS
       it  was  avg  48  kB/s  with  peak  CPU at 98% (Pentium M 1.8 GHz). The
       extreme difference in resource usage is one of many important  benefits
       for  laptop  use.   Peak  memory consumption (several complex sites, 50
       paralell connections/threads; values are in KiB):

              VSZ   RSS CMD
             3204  1436 ./cntlm -f -c ./cntlm.conf -P pid
           411604  6264 /usr/share/ntlmaps/ -c /etc/ntlmaps/server.cfg

       Inherent part of the development is  profiling  and  memory  management
       screening  using  Valgrind.  The  source  distribution  contains a file
       called valgrind.txt, where you  can  see  the  report  confirming  zero
       leaks,  no access to unallocated memory, no usage of uninitialized data
       - all tracked down to  each  CPU  instruction  emulated  in  Valgrind’s
       virtual CPU during a typical production lifetime of the proxy.


       Most  options  can  be  pre-set  in a configuration file. Specifying an
       option more than once is not an error, but cntlm ignores all occurences
       except  the  last  one. This does not apply to options like -L, each of
       which creates a new instance of some feature. Cntlm can be built with a
       hardcoded  configuration  file  (e.g. /etc/cntlm.conf), which is always
       loaded, if possible.  See -c option on how to override some or  all  of
       its settings.

       Use -h to see available options with short description.

       -A IP/mask    (Allow)
              Allow  ACL  rule. Together with -D (Deny) they are the two rules
              allowed in ACL policy. It is  more  usual  to  have  this  in  a
              configuration  file,  but Cntlm follows the premise that you can
              do the same on the command-line as  you  can  using  the  config
              file.  When  Cntlm  receives  a  connection  request, it decides
              whether to allow or deny it. All ACL rules are stored in a  list
              in  the  same  order as specified. Cntlm then walks the list and
              the first IP/mask rule that matches the request  source  address
              is  applied.   The mask can be any number from 0 to 32, where 32
              is the default (that is exact IP match). This notation  is  also
              known  as  CIDR.  If you want to match everything, use 0/0 or an
              asterix. ACLs on the command-line take precedence over those  in
              the  config  file. In such case, you will see info about that in
              the log (among the list of unused options). There you  can  also
              see  warnings  about possibly incorrect subnet spec, that’s when
              the IP part has  more  bits  than  you  declare  by  mask  (e.g.
     should be

       -a NTLMv2 | NTLM2SR | NT | NTLM | LM    (Auth)
              Authentication  type.  NTLM(v2)  comprises  of one or two hashed
              responses, NT and LM or NTLM2SR or  NTv2  and  LMv2,  which  are
              computed  from the password hash. Each response uses a different
              hashing algorithm; as new response types were invented, stronger
              algorithms  were  used.  When  you first install cntlm, find the
              strongest one which works for you (preferably  using -M).  Above
              they  are  listed from strongest to weakest. Very old servers or
              dedicated HW proxies might be unable to process anything but LM.
              If  none  of  those  work,  see compatibility flags option -F or
              submit a Support Request.

              IMPORTANT:  Although  NTLMv2  is  not   widely   adopted   (i.e.
              enforced),  it  is  supported  on  all Windows since NT 4.0 SP4.
              That’s for a very long time! I strongly suggest you  use  it  to
              protect  your  credentials  on-line.  You  should  also  replace
              plaintext  Password  options  with   hashed   Pass[NTLMv2|NT|LM]
              equivalents.  NTLMv2  is  the  most and possibly the only secure
              authentication of the NTLM family.

       -B    (NTLMToBasic)
              This option enables "NTLM-to-basic", which allows you to use one
              cntlm  for multiple users. Please note that all security of NTLM
              is lost this  way.  Basic  auth  uses  just  a  simple  encoding
              algorithm  to  "hide" your credentials and it is moderately easy
              to sniff them.

              IMPORTANT:  HTTP  protocol  obviously  has  means  to  negotiate
              authorization  before  letting  you  through, but TCP/IP doesn’t
              (i.e. open port is open port).  If  you  use  NTLM-to-basic  and
              DON’T  specify some username/password in the configuration file,
              you are bound to loose tunneling features, because  cntlm  alone
              won’t know your credentials.

              Because  NTLM identification has at least three parts (username,
              password, domain) and the basic authentication  provides  fields
              for  only  two  (username,  password),  you  have to smuggle the
              domain part somewhere. You can set  the  Domain  config/cmd-line
              parameter,  which  will  then  be  used for all users, who don’t
              specify their domain as a part of the username. To do  that  and
              override  the  global  domain setting, use this instead of plain
              username in the password dialog: "domain\username".

       -c <filename>
              Configuration file. Command-line options, if used, override  its
              single  options  or  are  added at the top of the list for multi
              options (tunnels, parent proxies, etc)  with  the  exception  of
              ACLs,  which  are completely overriden. Use /dev/null to disable
              any config file.

       -D IP/mask    (Deny)
              Deny ACL rule. See option -A above.

       -d <domain>    (Domain)
              The domain or workgroup of the proxy  account.  This  value  can
              also be specified as a part of the username with -u.

       -F <flags>    (Flags)
              NTLM  authentication  flags. This option is rater delicate and I
              do not recommend to change the default  built-in  values  unless
              you  had  no  success  with  parent  proxy  auth and tried magic
              autodetection (-M) and all possible values for the  Auth  option
              (-a).   Remember  that  each  NT/LM  hash  combination  requires
              different flags. This option  is  sort  of  a  complete  "manual
              override" and you’ll have to deal with it yourself.

       -f     Run in console as a foreground job, do not fork into background.
              In this mode, all syslog messages will be echoed to the  console
              (on  platforms  which  support syslog LOG_PERROR option). Though
              cntlm is primarily  designed  as  a  classic  UNIX  daemon  with
              syslogd  logging,  it  provides  detailed  verbose  mode without
              detaching from the controlling terminal; see -v.  In  any  case,
              all  error and diagnostic messages are always sent to the system

       -G <pattern>    (ISAScannerAgent)
              User-Agent matching (case insensitive) for trans-isa-scan plugin
              (see  -S  for  explanation).  Positive match identifies requests
              (applications) for which the plugin should  be  enabled  without
              considering the size of the download (see -S). You can use shell
              wildcard characters, namely "*", "?" and "[]". If  used  without
              -S  or  ISAScannerSize,  the max_size_in_kb is internally set to
              infinity, so the plugin will be active ONLY for  selected  User-
              Agents, regardless of download size.

       -g    (Gateway)
              Gateway  mode,  cntlm listens on all network interfaces. Default
              is to bind just loopback. That way,  only  local  processes  can
              connect  to  cntlm. In the gateway mode though, cntlm listens on
              all interfaces and  is  accessible  to  other  machines  on  the
              network.  Please  note  that  with  this option the command-line
              order matters when specifying proxy or tunnel local  (listening)
              ports. Those positioned before it will bind only loopback; those
              after will be public.
              IMPORTANT: All of the above applies  only  to  local  ports  for
              which  you  didn’t specify any source address. If you did, cntlm
              tries to bind the given port only on the specified interface (or
              rather IP address).

       -H     Use  this  option to get hashes for password-less configuration.
              In this mode, cntlm prints the results and exits. You  can  just
              copy  &  paste right into the config file. You ought to use this
              option with explicit -u and -d, because some hashes include  the
              username  and  domain  name  in  the  calculation. Do see -a for
              security recommendations.

       -h     Display help (available options with a  short  description)  and

       -I     Interactive  password  prompt.  Any  password  settings from the
              command line or config file is ignored and a password prompt  is
              issued. Use this option only from shell.

       -L [<saddr>:]<lport>:<rhost>:<rport>    (Tunnel)
              Tunnel  specification.  The  syntax  is the same as in OpenSSH’s
              local forwarding (-L), with a new optional prefix, saddr  -  the
              source  IP  address  to bind the lport to. Cntlm will listen for
              incomming connections on the local port lport, forwarding  every
              new  connection  through  the  parent  proxy  to the rhost:rport
              (authenticating on the go). This option  can  be  used  multiple
              times for unlimited number of tunnels, with or without the saddr
              option. See -g for the details  concerning  local  port  binding
              when saddr is not used.

              Please note that many corporate proxies do not allow connections
              to ports other than 443 (https), but  if  you  run  your  target
              service  on  this  port, you should be safe. Connect to HTTPS is
              "always" allowed, otherwise  nobody  would  be  able  to  browse
              https://  sites.  In  any case, first try if you can establish a
              connection through the tunnel,  before  you  rely  on  it.  This
              feature  does  the  same  job  as  tools  like corkscrew(1), but
              instead of communicating over a terminal, cntlm keeps it TCP/IP.

       -l [<saddr>:]<lport>    (Listen)
              Local  port for the cntlm proxy service. Use the number you have
              chosen here and  the  hostname  of  the  machine  running  cntlm
              (possibly  localhost)  as  proxy settings in your browser and/or
              the environment.  Most applications (including console)  support
              the notion of proxy to connect to other hosts. On POSIX, set the
              following variables to use  e.g.  wget(1)  without  any  trouble
              (fill in the actual address of cntlm):

                  $ export ftp_proxy=http://localhost:3128
                  $ export http_proxy=$ftp_proxy
                  $ export https_proxy=$ftp_proxy

              You  can  choose to run the proxy service on more than one port,
              in such case just use this option as many  times  as  necessary.
              But  unlike  tunnel  specification,  cntlm  fails to start if it
              cannot bind all of the proxy service ports.  Proxy service  port
              can  also  be  bound  selectively.  Use  saddr to pick source IP
              address to bind the lport to. This allows you, for  example,  to
              run  the  service on different ports for subnet A and B and make
              it invisible for subnet C. See -g  for  the  details  concerning
              local port binding when saddr is not used.

       -M <testurl>
              Run magic NTLM dialect detection. In this mode, cntlm tries some
              known working presets against your  proxy.  Probe  requests  are
              made  for the specified testurl, with the strongest hashes going
              first.  When finished, settings for the most  secure  setup  are
              printed.  Although  the detection will tell you which and how to
              use Auth, Flags and password-hash options, you have to configure
              at  least  your credentials and proxy address first. You can use
              -I to enter your password interactively.

       -O [<saddr>:]<port_number>    (SOCKS5Proxy)
              Enable SOCKS5 proxy and make it listen on local port port_number
              (source  IP  spec  is  also  possible,  as with all options). By
              default, there will be no restrictions as to who  can  use  this
              service.  Some  clients don’t even support SOCKS5 authentication
              (e.g.  almost  all   browsers).   If   you   wish   to   enforce
              authentication,  use -R or its equivalent option, SOCKS5User. As
              with port tunneling, it is up to the  parent  proxy  whether  it
              will  allow  connection to any requested host:port. This feature
              can be used with tsocks(1) to make most TCP/IP  applications  go
              thru  the  proxy rather than directly (only outgoing connections
              will work, obviously). To make apps work without DNS server,  it
              is  important  that  they  don’t  resolve  themselves, but using
              SOCKS. E.g.  Firefox  has  this  option  available  through  URI
              "about:config",  key  name network.proxy.socks_remote_dns, which
              must be set to true. Proxy-unaware tsocksified apps,  will  have
              to  be  configured  using  IP addresses to prevent them from DNS

       -P <pidfile>
              Create a PID file pidfile upon startup. If  the  specified  file
              exists,  it  is  truncated  and  overwritten.   This  option  is
              intended for use with start-stop-daemon(8) and  other  servicing
              mechanisms.  Please  note that the PID file is created AFTER the
              process drops its privileges and forks. When the daemon finishes
              cleanly, the file is removed.

       -p <password>    (Password, PassNT, ...)
              Proxy  account  password.  Cntlm  deletes  the password from the
              memory, to make it invisible in /proc or with  inspection  tools
              like ps(1), but the preferable way of specifying password is the
              configuration file. To that end, you  can  use  Password  option
              (for  plaintext,  human  readable  format),  or  "encrypt"  your
              password via -H and then use PassNTLMv2, PassNT and/or PassLM.

       -R <username>:<password>    (SOCKS5User)
              If SOCKS5 proxy is enabled, this option can make  it  accessible
              only  to those who have been authorized.  It can be used several
              times, to create a whole list  of  accounts  (allowed  user:pass

       -S <max_size_in_kb>    (ISAScannerSize)
              Enables  the  plugin for transparent handling of the dreaded ISA
              AV scanner, which returns an interactive HTTP  page  (displaying
              the   scanning   progress)   instead  of  the  file/data  you’ve
              requested, every time it feels like scanning the contents.  This
              presumptuous behavior breaks every automated downloader, updater
              and basically EVERY application relying on downloads (e.g. wget,

              The  parameter  max_size_in_kb  allows  you  to  choose  maximum
              download size you wish to handle by the plugin  (see  below  why
              you  might  want  that).  If  the file size is bigger than this,
              cntlm forwards you the interactive page,  effectively  disabling
              the   plugin  for  that  download.  Zero  means  no  limit.  Use
              -G/ISAScannerAgent   to   identify   applications   for    which
              max_size_in_kb  should be ignored (forcing the plugin). It works
              by matching User-Agent header and is necessary  for  e.g.  wget,
              apt-get  and  yum, which would fail if the response is some HTTP
              page instead of requested data.

              How it works: the client asks for a file,  cntlm  detects  ISA’s
              bullshit  response and waits for the secret link to ISA’s cache,
              which comes no sooner than the file is downloaded and scanned by
              ISA.  Only  then  can cntlm make the second request for the real
              file and forward it along with correct headers  to  the  client.
              The  client  doesn’t  timeout while waiting for it, b/c cntlm is
              periodically sending an extra "keepalive" header, but  the  user
              might  get  nervous  not  seeing  the progress bar move. It’s of
              course purely psychological matter,  there’s  no  difference  if
              cntlm  or your browser requests the scanned file - you must wait
              for ISA to do it’s job and download then. You just expect to see
              some  progress  indicator move, which is all what the ISA’s page
              does: it shows HTML countdown.

              If the plugin cannot parse the interactive page for some  reason
              (unknown  formatting,  etc.), it quits and the page is forwarded
              to you - it’s never "lost".

              The keepalive header  is  called  ISA-Scanner  and  shows  ISA’s
              progress, e.g.:

                  HTTP/1.1 200 OK
                  ISA-Scanner: 1000 of 10000
                  ISA-Scanner: 2000 of 10000

       -r "<name>: <value>"    (Header)
              Header  substitution.  Every  client’s request will be processed
              and any headers defined using -r or in  the  configuration  file
              will  be added to it. In case the header is already present, its
              value will be replaced.

       -s     Serializes all requests by  not  using  concurrent  threads  for
              proxy  (tunneling  still works in parallel). This has a horrible
              impact on  performance  and  is  available  only  for  debugging
              purposes.  When  used  with  -v, it yields nice sequential debug
              log, where requests take turns.

       -T <filename>
              Used in combination with -v to save  the  debug  output  into  a
              trace  file.   It should be placed as the first parameter on the
              command line. To prevent  data  loss,  it  never  overwrites  an
              existing file. You have to pick a unique name or manually delete
              the old file.

       -U <uid>
              When executed as root, do the stuff that needs such  permissions
              (read  config,  bind  ports,  etc.)  and  then  immediately drop
              privileges and change to uid.   This  parameter  can  be  either
              number  or  system  username.  If you use a number, both uid and
              gid of the process will be set to this value; if you  specify  a
              username,  uid  and gid will be set according to that user’s uid
              and primary gid as defined in /etc/passwd. You  should  use  the
              latter,  possibly  using  a dedicated cntlm account. As with any
              daemon, you are strongly advised  to  run  cntlm  under  a  non-
              privileged account.

       -u <user>[@<domain>]    (Username)
              Proxy account/user name. Domain can be be entered as well.

       -v     Print debugging information. Automatically enables (-f).

       -w <workstation>    (Workstation)
              Workstation  NetBIOS  name.  Do  not use full domain name (FQDN)
              here. Just the first part. If not specified, cntlm tries to  get
              the  system  hostname  and  if  that  fails, uses "cntlm" - it’s
              because some proxies require this field non-empty.


       Configuration file has  the  same  syntax  as  OpenSSH  ssh_config.  It
       comprises  of  whitespace delimited keywords and values. Comment begins
       with a hash ’#’ and can begin anywhere in the  file.  Everything  after
       the  hash  up  until  the  EOL  is  a  comment.  Values can contain any
       characters, including whitespace. Do not quote anything.  For  detailed
       explanation   of   keywords,   see  appropriate  command-line  options.
       Following keywords are available:

       Allow <IP>[/<mask>]
              ACL allow rule, see -A.

       Auth NTLMv2 | NTLM2SR | NT | NTLM | LM
              Select any possible combination of NTLM hashes  using  a  single

       Deny <IP>[/<mask>]
              ACL deny rule, see -A.

       Domain <domain_name>
              Proxy account domain/workgroup name.

       Flags <flags>
              NTLM authentication flags. See -F for details.

       Gateway yes|no
              Gateway  mode.  In the configuration file, order doesn’t matter.
              Gateway mode applies the same to all tunnels.

       Header <headername: value>
              Header  substitution.  See  -r  for  details  and  remember,  no

       ISAScannerAgent <pattern>
              Wildcard-enabled  (*,  ?, []) case insensitive User-Agent string
              matching  for  the  trans-isa-plugin.  If   you   don’t   define
              ISAScannerSize, it is internally set to infinity, i.e. disabling
              the plugin for all downloads except  those  agent-matched  ones.
              See -G.

       ISAScannerSize <max_size_in_kb>
              Enable trans-isa-scan plugin. See -S for more.

       Listen [<saddr>:]<port_number>
              Local  port  number  for  the  cntlm’s proxy service. See -l for

       Password <password>
              Proxy account password.

       PassNTLMv2, PassNT, PassLM <password>
              Hashes of the proxy account password (see -H and -a).  When  you
              want   to  use  hashes  in  the  config  (instead  of  plaintext
              password), each Auth settings requires different options:

                  Settings     |  Requires
                  Auth NTLMv2  |  PassNTLMv2
                  Auth NTLM2SR |  PassNT
                  Auth NT      |  PassNT
                  Auth NTLM    |  PassNT + PassLM
                  Auth LM      |  PassLM

       Proxy <host:port>
              Parent proxy, which requires authentication. The same  as  proxy
              on  the  command-line,  can  be  used  more than once to specify
              unlimited number  of  proxies.  Should  one  proxy  fail,  cntlm
              automatically  moves  on  to  the  next one. The connect request
              fails only if the whole list of proxies is scanned and (for each
              request)  and found to be invalid. Command-line takes precedence
              over the configuration file.

       SOCKS5Proxy [<saddr>:]<lport>
              Enable SOCKS5 proxy. See -O for more.

       SOCKS5User <username>:<password>
              Create a new SOCKS5 proxy account. See -R for more.

       NTLMToBasic yes|no
              Enable/disable NTLM-to-basic authenticatoin. See -B for more.

       Tunnel [<saddr>:]<lport>:<rhost>:<rport>
              Tunnel specification. See -L for more.

              Proxy account name, without the possibility  to  include  domain
              name (’at’ sign is interpreted literally).

       Workstation <hostname>
              The hostname of your workstation.


       The  optional  location  of  the  configuration  file is defined in the
       Makefile, with the default  for  1)  deb/rpm  package,  2)  traditional
       "make; make install" and 3) Windows installer being:

           1) /etc/cntlm.conf
           2) /usr/local/etc/cntlm.conf
           3) %PROGRAMFILES%\Cntlm\cntlm.ini


       Cntlm  has been successfully compiled and tested on both little and big
       endian machines (Linux/i386 and AIX/PowerPC). For compilation  details,
       see  README in the source distribution. Porting to any POSIX conforming
       OS shouldn’t be more than a matter of the Makefile rearrangement. Cntlm
       uses  strictly POSIX.1-2001 interfaces with ISO C99 libc (snprintf(3)),
       it is also compliant with SUSv3. Since  version  0.33,  cntlm  supports
       Windows using POSIX emulation layer Cygwin.


       In  the  much needed NTLM-proxy departement, cntlm aims to be a drop-in
       replacement for NTLMAPS. But please note that NTLM WWW  auth  (that  is
       auth to HTTP servers), when it is running without any parent proxy as a
       standalone proxy server in itself, won’t probaly be  implemented  ever.
       Even  though  the  tasks  share  common  NTLM  authentication, they are
       different things. Also,  I’ve  never  seen  any  access-protected  HTTP
       server  requiring  solely  NTLM without any alternative. Such a narrow-
       spectrum tool can be written in Perl in a few minutes. I strive to keep
       the code of cntlm simple and efficient.


       This software is still BETA, so there are probably many bugs for you to
       uncloak even though I’m testing every new piece of code  AMAP  and  use
       cntlm  daily.  I’ll be happy to fix all of them, but if you can manage,
       patches would be better. ;)

       To report a bug, enable the debug output, save it to a file and  submit
       on-line  along  with  a  detailed description of the problem and how to
       reproduce it. The link can be found on the homepage.

       To generate the debug tracefile correctly, first  run  cntlm  from  the
       shell  (command line) and make sure you can reproduce the bug. When you
       will have  verfied  that,  stop  cntlm  (hit  Ctrl-C)  and  insert  the
       following  parameters  at the beginning of the command line, preserving
       their order.  Example:

           cntlm[.exe] -T cntlmtrace.log -v -s ... the rest ...


       Written by David Kubicek <dave (o)>


       Copyright © 2007 David Kubicek
       Cntlm uses DES, MD4, MD5 and HMAC-MD5 routines from gnulib  and  Base64
       routines from mutt(1).