Skip to content
Projects
Groups
Snippets
Help
Loading...
Help
Submit feedback
Contribute to GitLab
Sign in
Toggle navigation
V
varnish-cache
Project
Project
Details
Activity
Releases
Cycle Analytics
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Charts
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Charts
Commits
Open sidebar
varnishcache
varnish-cache
Commits
a5bfbaba
Commit
a5bfbaba
authored
Feb 15, 2021
by
Poul-Henning Kamp
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Move the API aspects of VCLI to the reference manual.
parent
49f4f916
Changes
3
Hide whitespace changes
Inline
Side-by-side
Showing
3 changed files
with
129 additions
and
103 deletions
+129
-103
cli_protocol.rst
doc/sphinx/reference/cli_protocol.rst
+126
-0
index.rst
doc/sphinx/reference/index.rst
+2
-1
varnish-cli.rst
doc/sphinx/reference/varnish-cli.rst
+1
-102
No files found.
doc/sphinx/reference/cli_protocol.rst
0 → 100644
View file @
a5bfbaba
.. role:: ref(emphasis)
.. _ref_cli_api:
===========================================
VCLI protocol - Scripting the CLI interface
===========================================
The Varnish CLI has a few bells&whistles when used as an API.
First: `vcli.h` contains magic numbers.
Second: If you use `varnishadm` to connect to `varnishd` use the
`-p` argument to get "pass" mode.
In "pass" mode, or with direct CLI connections (more below), the
first line of responses is always exactly 13 bytes long, including
the NL, and it contains two numbers: The status code and the count
of bytes in the remainder of the response::
200␣19
PONG␣1613397488␣1.0
This makes parsing the response unambiguous, even in cases like this
where the response does not end with a NL.
The varnishapi library contains functions to implement the basics of
the CLI protocol, for more, see the `vcli.h` include file.
.. _ref_psk_auth:
Authentication CLI connections
------------------------------
CLI connections to `varnishd` are authenticated with a "pre-shared-key"
authentication scheme, where the other end must prove they know the
contents of a particular file, either by being able to access it on
the machine `varnishd` runs on, usually via information in `VSM` or
by having a local copy of the file on another machine.
The precise filename can be configured with the `-S` option to `varnishd`
and regular file system permissions control access to it.
The file is only read at the time the `auth` CLI command is issued
and the contents is not cached in `varnishd`, so it is possible to
change the contents of the file while `varnishd` is running.
An authenticated session looks like this:
.. code-block:: text
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 279
-----------------------------
Varnish Cache CLI 1.0
-----------------------------
FreeBSD,13.0-CURRENT,amd64,-jnone,-sdefault,-sdefault,-hcritbit
varnish-trunk revision 89a558e56390d425c52732a6c94087eec9083115
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. The
first 32 characters of the response text is the challenge
"ixsl...mpg". The challenge is randomly generated for each CLI
connection, 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 string
* Newline (0x0a) character.
* Contents of the secret file
* Challenge string
* Newline (0x0a) character.
and dumping the resulting digest in lower-case hex.
In the above example, the secret file contains ``foo\n`` and thus:
.. code-block:: text
critter phk> hexdump secret
00000000 66 6f 6f 0a |foo.|
00000004
critter phk> cat > tmpfile
ixslvvxrgkjptxmcgnnsdxsvdmvfympg
foo
ixslvvxrgkjptxmcgnnsdxsvdmvfympg
^D
critter phk> hexdump -C tmpfile
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 tmpfile
SHA256 (_) = 455ce847f0073c7ab3b1465f74507b75d3dc064c1e7de3b71e00de9092fdc89a
critter phk> openssl dgst -sha256 < tmpfile
455ce847f0073c7ab3b1465f74507b75d3dc064c1e7de3b71e00de9092fdc89a
The sourcefile `lib/libvarnish/cli_auth.c` contains a useful function
which calculates the response, given an open filedescriptor to the
secret file, and the challenge string.
See also:
---------
* :ref:`varnishadm(1)`
* :ref:`varnishd(1)`
* :ref:`vcl(7)`
doc/sphinx/reference/index.rst
View file @
a5bfbaba
...
@@ -42,7 +42,7 @@ The CLI interface
...
@@ -42,7 +42,7 @@ The CLI interface
:maxdepth: 1
:maxdepth: 1
VarnishAdm - Control program for Varnish <varnishadm>
VarnishAdm - Control program for Varnish <varnishadm>
V
CLI - The commands varnish understands <varnish-cli>
CLI - The commands varnish understands <varnish-cli>
Logging and monitoring
Logging and monitoring
----------------------
----------------------
...
@@ -93,6 +93,7 @@ For Developers
...
@@ -93,6 +93,7 @@ For Developers
VMODS - Extensions to VCL <vmod>
VMODS - Extensions to VCL <vmod>
VSM - Shared memory use <vsm>
VSM - Shared memory use <vsm>
VDIR - Backends & Directors <directors>
VDIR - Backends & Directors <directors>
VCLI - CLI protocol API <cli_protocol>
.. Vmod_debug ?
.. Vmod_debug ?
...
...
doc/sphinx/reference/varnish-cli.rst
View file @
a5bfbaba
...
@@ -317,108 +317,6 @@ that can be be later reacquired. You can manually set the temperature
...
@@ -317,108 +317,6 @@ that can be be later reacquired. You can manually set the temperature
of a VCL or let varnish
of a VCL or let varnish
automatically handle it.
automatically handle it.
Scripting
---------
If you are going to write a script that talks CLI to varnishd, the
include/cli.h contains the relevant magic numbers.
One particular magic number to know, is that the line with the status
code and length field always is exactly 13 characters long, including
the NL character.
The varnishapi library contains functions to implement the basics of
the CLI protocol, see the `vcli.h` include file.
.. _ref_psk_auth:
Authentication with -S
----------------------
If the -S secret-file is given as argument to varnishd, all network
CLI connections must authenticate, by proving they know 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:
.. code-block:: text
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 279
-----------------------------
Varnish Cache CLI 1.0
-----------------------------
FreeBSD,13.0-CURRENT,amd64,-jnone,-sdefault,-sdefault,-hcritbit
varnish-trunk revision 89a558e56390d425c52732a6c94087eec9083115
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. The
first 32 characters of the response text is the challenge
"ixsl...mpg". The challenge is randomly generated for each CLI
connection, 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 string
* Newline (0x0a) character.
* Contents of the secret file
* Challenge string
* Newline (0x0a) character.
and dumping the resulting digest in lower-case hex.
In the above example, the secret file contains ``foo\n`` and thus:
.. code-block:: text
critter phk> hexdump secret
00000000 66 6f 6f 0a |foo.|
00000004
critter phk> cat > tmpfile
ixslvvxrgkjptxmcgnnsdxsvdmvfympg
foo
ixslvvxrgkjptxmcgnnsdxsvdmvfympg
^D
critter phk> hexdump -C tmpfile
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 tmpfile
SHA256 (_) = 455ce847f0073c7ab3b1465f74507b75d3dc064c1e7de3b71e00de9092fdc89a
critter phk> openssl dgst -sha256 < tmpfile
455ce847f0073c7ab3b1465f74507b75d3dc064c1e7de3b71e00de9092fdc89a
The sourcefile lib/libvarnish/cli_auth.c contains a useful function
which calculates the response, given an open filedescriptor to the
secret file, and the challenge string.
EXAMPLES
EXAMPLES
========
========
...
@@ -456,3 +354,4 @@ SEE ALSO
...
@@ -456,3 +354,4 @@ SEE ALSO
* :ref:`varnishadm(1)`
* :ref:`varnishadm(1)`
* :ref:`varnishd(1)`
* :ref:`varnishd(1)`
* :ref:`vcl(7)`
* :ref:`vcl(7)`
* For API use of the CLI: The Reference Manual.
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment