CLI documentation

Authentication

If the -S secret-file is given as argument to varnishd, all telnet CLI connections must authenticate, by proving they can read the contents of that file.

The file is read at the time the auth command is issued and the contents is not cached in varnishd, so it is possible to update the file on the fly.

Use the unix file permissions to control access to the file.

An authenticated session looks like this:

critter phk> telnet localhost 1234
Trying ::1...
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
107 59      
ixslvvxrgkjptxmcgnnsdxsvdmvfympg

Authentication required.

auth 455ce847f0073c7ab3b1465f74507b75d3dc064c1e7de3b71e00de9092fdc89a
200 193     
-----------------------------
Varnish HTTP accelerator CLI.
-----------------------------
Type 'help' for command list.
Type 'quit' to close CLI session.
Type 'start' to launch worker process.

The CLI status of 107 indicates that authentication is necessary. All characters up to the first NL on the first line in the response text is the challenge (ixsl...mpg). The challenge is randomly generated and changes each time a 107 is emitted. The most recently emitted challenge must be used for calculating the authenticator (455c...c89a).

The authenticator is calculated by applying the SHA256 function to the following byte sequence:

• Challenge followed by NL
• Contents of the secret file
• Challenge followed by NL

and dumping the resulting digest in lower-case hex.

In the above example, the secret file contained foo\n and thus:

critter phk> cat > _
ixslvvxrgkjptxmcgnnsdxsvdmvfympg
foo
ixslvvxrgkjptxmcgnnsdxsvdmvfympg
^D
critter phk> hexdump -C _
00000000  69 78 73 6c 76 76 78 72  67 6b 6a 70 74 78 6d 63  |ixslvvxrgkjptxmc|
00000010  67 6e 6e 73 64 78 73 76  64 6d 76 66 79 6d 70 67  |gnnsdxsvdmvfympg|
00000020  0a 66 6f 6f 0a 69 78 73  6c 76 76 78 72 67 6b 6a  |.foo.ixslvvxrgkj|
00000030  70 74 78 6d 63 67 6e 6e  73 64 78 73 76 64 6d 76  |ptxmcgnnsdxsvdmv|
00000040  66 79 6d 70 67 0a                                 |fympg.|
00000046
critter phk> sha256 _ 
SHA256 (_) = 455ce847f0073c7ab3b1465f74507b75d3dc064c1e7de3b71e00de9092fdc89a

Please notice that the connection is not encrypted, it is only authenticated.