Main Page
From cntlm
Contents |
Cntlm Knowledge Base
You are encouraged to share your experience with Cntlm here - its configuration, usage or HOWTOs. Other users will only benefit if you jot down the exotic settings (e.g. if -M failed) for your proxy, etc. Also try to include as much information about your setup and the environment as possible: Cntlm version, OS version, proxy type/name/version...
Before you do anything, get the latest version and browse our SF.net Tracker and Forums. You could find the answer there.
Configuration file syntax
Some of you are not familiar with text configuration files. I use the same file syntax on all platforms because of portability, so please don't ask me to move the configuration into Windows registry, etc. :) Now the rules:
- Empty lines and lines beginning with a hash sign ( # ) are ignored. To enable a hashed-out (disabled) option, just delete the sign.
- The options are not case sensitive. This means you can use Listen just as well as listen.
- Each option accepts only one value. Some options (e.g. Proxy or SOCKS5User) can be used repeatedly to allow for more values (see manual).
- To separate the option-value pair, use any white space. This can be a space, several spaces or a tab character. Never use the equals sign ( = )!
- Values are parsed literally, that means no quoting. If your value contains spaces, the parser can deal with it. Do not use any quotes.
You can find an example of this syntax in the Troubleshooting section.
Tying up the loose ends
When you have Cntlm up and running, you have to instruct your applications to use it first. It doesn't happen automagically. Most apps allow you to change the default network connection parameters. I dare to say, except for P2P and a few other special cases, every app is able to use a proxy to access the Internet. By default, apps usually access the net directly. You have to tell them to use this special gateway, the proxy. What you're looking for is a place, where you can specify the proxy host, port and type. Cntlm can act as a so-called HTTP proxy or some place also HTTPS proxy. There is at least one other frequent proxy type, SOCKS, which I'll speak of later. When you have selected the HTTP(S) type, you have to specify the proxy host. For Cntlm, this usually amounts to just using "localhost". If Cntlm is running on a different computer than the app in question, you must use the name of that computer instead. The last thing is the port number. This number depends solely on the Cntlm configuration. You pick this number when configuring Cntlm. It is the same number you set for the Listen (or Tunnel) option.
Follow this link for a comprehensive MSIE guide to setting a proxy server. This is a different guide for MSIE, Firefox, Netscape, Windows Media Player, etc. You will probably want to change this settings for other apps like: universal downloader, instant messenger, subversion client, VoIP suite, etc. Either look that up in their documentation or check out the Settings or Properties dialogs.
That's it, now you should have your app ready to access the net via Cntlm.
Troubleshooting
It is unlikely you'll need this section, as Cntlm can do and auto-detect more than default Windows, but I've seen some snags because of crazy admins and exotic proxies. This is here so I don't have to repeat it each time somebody hits the wall. :) NTLM auth is also kinda complicated piece of crap with many knobs and I think some extra documentation will come in handy.
So, I assume you know and have already tried magic NTLM auto detection using -M. If not, do so now. It will print out the most secure configuration which works with your proxy. If you get successful result, you're finished.
If you don't, you screwed your credentials, have a very exotic proxy, or some extra "security" measures employed by the administrator. What follows is a list of different ideas and unfortunately, there are many possible combinations. These are some safe values; while guessing one option at a time, set others like this unless you know better:
Username your_domain_user Password your_domain_password Domain your_domain Workstation netbios_name_of_windows_workstation_where_browsing_works Auth LM Flags 0x06820000 Header User-Agent: Mozilla/4.0 (compatible; MSIE 5.5; Windows 98)
While testing, set plain text password via Password option. Do not use PassNTLMv2, PassNT or PassLM. This is to eliminate other possible points of failure (some hashes are bound to a particular Username or Domain and we want to be sure that our credentials are OK while testing). When you have your settings right, feel free to run cntlm -H to get relevant password hashes and substitute them for the plain text.
If this safe config doesn't work, you should try different Auth settings. Try Auth NTLM, then Auth LM and in both cases make sure you removed Flags from now on (it's just for safe-mode LM auth). Every time you change your configuration, restart Cntlm, otherwise it won't use the new values.
In case there's no Auth settings working reliably, the problem might be elsewhere. It is possible that the proxy expects your requests to come from a certain "workstation". Cntlm can guess this name, but if you're running on an "unauthorized" machine/partition or if the name of your workstation (hostname) doesn't match this expected value, you will have to supply it using the Workstation option. I expect you know or can find out which name should go there. You can get it from a Windows machine, where browsing with MSIE (or whatever) works.
Other possibility is that the proxy requires certain headers to be present in your requests. This is used by insane admins to filter out "unsupported" web clients and browsers. Get yourself the whole User-Agent string of one of the supported browsers (e.g. from MSIE) and put it in your configuration. Make sure you delete the hash ( # ) sign on the beginning and replace the example with actual ID like this:
Header User-Agent: Mozilla/4.0 (compatible; MSIE 5.5; Windows 98)
Migrating from NTLMAPS
You can save yourself a lot of work, if you have used NTLMAPS previously. You already know which headers must be substituted, the workstation name you need and NT/LM combination. Most Cntlm options have similar names and the manual has info on how to mimic NTLM config from your old server.cfg. Basically, it's about proper Auth, Workstation and Header option(s).
When you are done, just relax and enjoy the fruits of your migration! :) If you want to make your setup more secure or use some of Cntlm's wonderful features, read the relevant manual section. Alas, we have to deal with crazy MS protocols and even though there's a lot of automation in Cntlm, some of you will have to get their hands dirty a bit, but when auth is working, everything is super smooth.
Requesting support
Nothing so far? Ok, I'll try to help, but I'm going to need some stuff. Not everything listed here might be necessary, but if it's about broken auth or proxy functionality, I'll definitely need all of it:
- Cntlm version, OS version, proxy name (ISA, Squid, Wingate, NetCache, etc.)
- Make sure your internet application (e.g. browser) has correct proxy settings, pointing to Cntlm - usually the host name is localhost and the port number can be found as the Listen option in cntlm.conf / cntlm.ini)
- Now generate a trace file:
- Stop Cntlm (the daemon / the service)
- Open shell window or cmd.exe and cd to the directory you have a writing permission for, e.g. your $HOME or Cntlm installation directory (for UNIX/Windows respectively)
- Run: cntlm -T cntlm.txt -v -f -s
- Reproduce the problem: use the browser for example; just do not browse like crazy - trace file would be HUGE and I'd reject it
- Kill Cntlm (hit Ctrl-C a few times, for example)
- Get cntlm.txt, it's the trace file
- Prepare a copy of your cntlm.conf / cntlm.ini and cntlm.txt
- Do not delete/change anything from the config file copy, only overwrite each letter of the password with an asterisk ( * )
- Put both files into a ZIP archive and attach to your problem description
You can either submit a Support Request on SF.net or mail me at <cntlm(o)awk(.)cz>
