1VARNISHD(1) VARNISHD(1)
2
6 varnishd - HTTP accelerator daemon
7
9 varnishd [-a address[:port]] [-b host[:port]] [-d] [-F] [-f config]
10 [-g group] [-h type[,options]] [-i identity] [-l shmlogsize] [-n
11 name] [-P file] [-p param=value] [-s type[,options]] [-T
12 address[:port]] [-t ttl] [-u user] [-V] [-w min[,max[,timeout]]]
13
15 The varnishd daemon accepts HTTP requests from clients, passes them on
16 to a backend server and caches the returned documents to better satisfy
17 future requests for the same document.
18
20 -a address[:port][,address[:port][...]
21 Listen for client requests on the specified address and port.
22 The address can be a host name (“localhost”), an IPv4 dot‐
23 ted-quad (“127.0.0.1”), or an IPv6 address enclosed in square
24 brackets (“[::1]”). If address is not specified, varnishd will
25 listen on all available IPv4 and IPv6 interfaces. If port is
26 not specified, the default HTTP port as listed in /etc/services
27 is used. Multiple listening addresses and ports can be speci‐
28 fied as a whitespace- or comma-separated list.
29 -b host[:port]
31 Use the specified host as backend server. If port is not speci‐
32 fied, the default is 8080.
33 -C Print VCL code compiled to C language and exit. Specify the VCL
35 file to compile with the -f option.
36 -d Enables debugging mode: The parent process runs in the fore‐
38 ground with a CLI connection on stdin/stdout, and the child
39 process must be started explicitly with a CLI command. Termi‐
40 nating the parent process will also terminate the child.
41 -F Run in the foreground.
43 -f config
45 Use the specified VCL configuration file instead of the builtin
46 default. See vcl(7) for details on VCL syntax.
47 -g group
49 Specifies the name of an unprivileged group to which the child
50 process should switch before it starts accepting connections.
51 This is a shortcut for specifying the group run-time parameter.
52 -h type[,options]
54 Specifies the hash algorithm. See Hash Algorithms for a list of
55 supported algorithms.
56 -i identity
58 Specify the identity of the varnish server. This can be
59 accessed using server.identity from VCL
60 -l shmlogsize
62 Specify size of shmlog file. Scaling suffixes like 'k', 'm' can
63 be used up to (e)tabytes. Default is 80 Megabytes. Specifying
64 less than 8 Megabytes is unwise.
65 -n name
67 Specify a name for this instance. Amonst other things, this
68 name is used to construct the name of the directory in which
69 varnishd keeps temporary files and persistent state. If the
70 specified name begins with a forward slash, it is interpreted as
71 the absolute path to the directory which should be used for this
72 purpose.
73 -P file
75 Write the process's PID to the specified file.
76 -p param=value
78 Set the parameter specified by param to the specified value.
79 See Run-Time Parameters for a list of parameters. This option
80 can be used multiple times to specify multiple parameters.
81 -S file
83 Path to a file containing a secret used for authorizing access
84 to the management port.
85 -s type[,options]
87 Use the specified storage backend. See Storage Types for a list
88 of supported storage types. This option can be used multiple
89 times to specify multiple storage files.
90 -T address[:port]
92 Offer a management interface on the specified address and port.
93 See Management Interface for a list of management commands.
94 -t ttl Specifies a hard minimum time to live for cached documents.
96 This is a shortcut for specifying the default_ttl run-time
97 parameter.
98 -u user
100 Specifies the name of an unprivileged user to which the child
101 process should switch before it starts accepting connections.
102 This is a shortcut for specifying the user run- time parameter.
103 If specifying both a user and a group, the user should be speci‐
105 fied first.
106 -V Display the version number and exit.
108 -w min[,max[,timeout]]
110 Start at least min but no more than max worker threads with the
112 specified idle timeout. This is a shortcut for specifying the
113 thread_pool_min, thread_pool_max and thread_pool_timeout run-time
114 parameters.
115 If only one number is specified, thread_pool_min and thread_pool_max
117 are both set to this number, and thread_pool_timeout has no effect.
118 Hash Algorithms
120 The following hash algorithms are available:
121 simple_list
123 A simple doubly-linked list. Not recommended for production
124 use.
125 classic[,buckets]
127 A standard hash table. This is the default. The hash key is
128 the CRC32 of the object's URL modulo the size of the hash table.
129 Each table entry points to a list of elements which share the
130 same hash key. The buckets parameter specifies the number of
131 entries in the hash table. The default is 16383.
132 critbit
134 A self-scaling tree structure. The default hash algorithm in
135 2.1. In comparison to a more traditional B tree the critbit tree
136 is almost completely lockless.
137 Storage Types
139 The following storage types are available:
140 malloc[,size]
142 Storage for each object is allocated with malloc(3).
143 The size parameter specifies the maximum amount of memory var‐
145 nishd will allocate. The size is assumed to be in bytes, unless
146 followed by one of the following suffixes:
147 K, k The size is expressed in kibibytes.
149 M, m The size is expressed in mebibytes.
151 G, g The size is expressed in gibibytes.
153 T, t The size is expressed in tebibytes.
155 The default size is unlimited.
157 file[,path[,size[,granularity]]]
159 Storage for each object is allocated from an arena backed by a
160 file. This is the default.
161 The path parameter specifies either the path to the backing file
163 or the path to a directory in which varnishd will create the
164 backing file. The default is /tmp.
165 The size parameter specifies the size of the backing file. The
167 size is assumed to be in bytes, unless fol‐ lowed by one of the
168 following suffixes:
169 K, k The size is expressed in kibibytes.
171 M, m The size is expressed in mebibytes.
173 G, g The size is expressed in gibibytes.
175 T, t The size is expressed in tebibytes.
177 % The size is expressed as a percentage of the free space
179 on the file system where it resides.
180 The default size is 50%.
182 If the backing file already exists, it will be truncated or
184 expanded to the specified size.
185 Note that if varnishd has to create or expand the file, it will
187 not pre-allocate the added space, leading to fragmentation,
188 which may adversely impact performance. Pre-creating the stor‐
189 age file using dd(1) will reduce fragmentation to a minimum.
190 The granularity parameter specifies the granularity of alloca‐
192 tion. All allocations are rounded up to this size. The size is
193 assumed to be in bytes, unless followed by one of the suffixes
194 described for size except for %.
195 The default size is the VM page size. The size should be
197 reduced if you have many small objects.
198 persistence[XXX]
200 New, shiny, better.
201 Management Interface
203 If the -T option was specified, varnishd will offer a command-line man‐
204 agement interface on the specified address and port. The following
205 commands are available:
206 help [command]
208 Display a list of available commands.
209 If the command is specified, display help for this command.
211 param.set param value
213 Set the parameter specified by param to the specified value.
214 See Run-Time Parameters for a list of parame‐ ters.
215 param.show [-l] [param]
217 Display a list if run-time parameters and their values.
218 If the -l option is specified, the list includes a brief expla‐
220 nation of each parameter.
221 If a param is specified, display only the value and explanation
223 for this parameter.
224 ping [timestamp]
226 Ping the Varnish cache process, keeping the connection alive.
227 purge field operator argument [&& field operator argument [...]]
229 Immediately invalidate all documents matching the purge expres‐
230 sion. See Purge expressions for more docu‐ mentation and exam‐
231 ples.
232 purge.list
234 Display the purge list.
235 All requests for objects from the cache are matched against
237 items on the purge list. If an object in the cache is older
238 than a matching purge list item, it is considered "purged", and
239 will be fetched from the backend instead.
240 When a purge expression is older than all the objects in the
242 cache, it is removed from the list.
243 purge.url regexp
245 Immediately invalidate all documents whose URL matches the spec‐
246 ified regular expression.
247 quit Close the connection to the varnish admin port.
249 start Start the Varnish cache process if it is not already running.
251 stats Show summary statistics.
253 All the numbers presented are totals since server startup; for a
255 better idea of the current situation, use the varnishstat(1)
256 utility.
257 status Check the status of the Varnish cache process.
259 stop Stop the Varnish cache process.
261 url.purge regexp
263 Deprecated, see purge.url instead.
264 vcl.discard configname
266 Discard the configuration specified by configname. This will
267 have no effect if the specified configuration has a non-zero
268 reference count.
269 vcl.inline configname vcl
271 Create a new configuration named configname with the VCL code
272 specified by vcl, which must be a quoted string.
273 vcl.list
275 List available configurations and their respective reference
276 counts. The active configuration is indicated with an asterisk
277 ("*").
278 vcl.load configname filename
280 Create a new configuration named configname with the contents of
281 the specified file.
282 vcl.show configname
284 Display the source code for the specified configuration.
285 vcl.use configname
287 Start using the configuration specified by configname for all
288 new requests. Existing requests will con‐ tinue using whichever
289 configuration was in use when they arrived.
290 Run-Time Parameters
292 Runtime parameters are marked with shorthand flags to avoid repeating
293 the same text over and over in the table below. The meaning of the
294 flags are:
295 experimental
297 We have no solid information about good/bad/optimal values for
298 this parameter. Feedback with experience and observations are
299 most welcome.
300 delayed
302 This parameter can be changed on the fly, but will not take
303 effect immediately.
304 restart
306 The worker process must be stopped and restarted, before this
307 parameter takes effect.
308 reload The VCL programs must be reloaded for this parameter to take
310 effect.
311 Here is a list of all parameters, current as of last time we remembered
313 to update the manual page. This text is produced from the same text
314 you will find in the CLI if you use the param.show command, so should
315 there be a new parameter which is not listed here, you can find the
316 description using the CLI commands.
317 Be aware that on 32 bit systems, certain default values, such as
319 sess_workspace (=16k) and thread_pool_stack (=64k) are reduced relative
320 to the values listed here, in order to conserve VM space.
321 acceptor_sleep_decay
323 Default: 0.900 Flags: experimental
324 If we run out of resources, such as file descriptors or worker
326 threads, the acceptor will sleep between accepts. This parame‐
327 ter (multiplicatively) reduce the sleep duration for each suc‐
328 cesfull accept. (ie: 0.9 = reduce by 10%)
329 acceptor_sleep_incr
331 Units: s Default: 0.001 Flags: experimental
332 If we run out of resources, such as file descriptors or worker
334 threads, the acceptor will sleep between accepts. This parame‐
335 ter control how much longer we sleep, each time we fail to
336 accept a new connection.
337 acceptor_sleep_max
339 Units: s Default: 0.050 Flags: experimental
340 If we run out of resources, such as file descriptors or worker
342 threads, the acceptor will sleep between accepts. This parame‐
343 ter limits how long it can sleep between attempts to accept new
344 connections.
345 auto_restart
347 Units: bool Default: on
348 Restart child process automatically if it dies.
350 ban_lurker_sleep
352 Units: s Default: 0.0
353 How long time does the ban lurker thread sleeps between success‐
355 full attempts to push the last item up the purge list. It
356 always sleeps a second when nothing can be done. A value of
357 zero disables the ban lurker.
358 between_bytes_timeout
360 Units: s Default: 60
361 Default timeout between bytes when receiving data from backend.
363 We only wait for this many seconds between bytes before giving
364 up. A value of 0 means it will never time out. VCL can override
365 this default value for each backend request and backend request.
366 This parameter does not apply to pipe.
367 cache_vbe_conns
369 Units: bool Default: off Flags: experimental
370 Cache vbe_conn's or rely on malloc, that's the question.
372 cc_command
374 Default: exec cc -fpic -shared -Wl,-x -o %o %s Flags:
375 must_reload
376 Command used for compiling the C source code to a dlopen(3)
378 loadable object. Any occurrence of %s in the string will be
379 replaced with the source file name, and %o will be replaced with
380 the output file name.
381 cli_buffer
383 Units: bytes Default: 8192
384 Size of buffer for CLI input. You may need to increase this if
386 you have big VCL files and use the vcl.inline CLI command. NB:
387 Must be specified with -p to have effect.
388 cli_timeout
390 Units: seconds Default: 10
391 Timeout for the childs replies to CLI requests from the master.
393 clock_skew
395 Units: s Default: 10
396 How much clockskew we are willing to accept between the backend
398 and our own clock.
399 connect_timeout
401 Units: s Default: 0.4
402 Default connection timeout for backend connections. We only try
404 to connect to the backend for this many seconds before giving
405 up. VCL can override this default value for each backend and
406 backend request.
407 default_grace
409 Default: 10seconds Flags: delayed
410 Default grace period. We will deliver an object this long after
412 it has expired, provided another thread is attempting to get a
413 new copy.
414 default_ttl
416 Units: seconds Default: 120
417 The TTL assigned to objects if neither the backend nor the VCL
419 code assigns one. Objects already cached will not be affected
420 by changes made until they are fetched from the backend again.
421 To force an immediate effect at the expense of a total flush of
422 the cache use "purge.url ."
423 diag_bitmap
425 Units: bitmap Default: 0 Bitmap controlling diagnostics code:
426 0x00000001 - CNT_Session states.
428 0x00000002 - workspace debugging.
429 0x00000004 - kqueue debugging.
430 0x00000008 - mutex logging.
431 0x00000010 - mutex contests.
432 0x00000020 - waiting list.
433 0x00000040 - object workspace.
434 0x00001000 - do not core-dump child process.
435 0x00002000 - only short panic message.
436 0x00004000 - panic to stderr.
437 0x00008000 - panic to abort2().
438 0x00010000 - synchronize shmlog.
439 0x00020000 - synchronous start of persistence.
440 0x80000000 - do edge-detection on digest.
441 Use 0x notation and do the bitor in your head :-)
443 err_ttl
445 Units: seconds Default: 0
446 The TTL assigned to the synthesized error pages
448 esi_syntax
450 Units: bitmap Default: 0 Bitmap controlling ESI parsing code:
451 0x00000001 - Don't check if it looks like XML
453 0x00000002 - Ignore non-esi elements
454 0x00000004 - Emit parsing debug records
455 Use 0x notation and do the bitor in your head :-)
457 fetch_chunksize
459 Units: kilobytes Default: 128 Flags: experimental
460 The default chunksize used by fetcher. This should be bigger
462 than the majority of objects with short TTLs. Internal limits
463 in the storage_file module makes increases above 128kb a dubious
464 idea.
465 first_byte_timeout
467 Units: s Default: 60
468 Default timeout for receiving first byte from backend. We only
470 wait for this many seconds for the first byte before giving up.
471 A value of 0 means it will never time out. VCL can override this
472 default value for each backend and backend request. This parame‐
473 ter does not apply to pipe.
474 group Default: ..... Flags: must_restart
476 The unprivileged group to run as.
478 http_headers
480 Units: header lines Default: 64
481 Maximum number of HTTP headers we will deal with. This space is
483 preallocated in sessions and workthreads only objects allocate
484 only space for the headers they store.
485 http_range
487 Default: off
488 Enables experimental support for the HTTP range header, enabling
490 Varnish to serve parts of an object to a client. However, Var‐
491 nish will request the whole object from the backend server.
492 listen_address
494 Default: :80 Flags: must_restart
495 Whitespace separated list of network endpoints where Varnish
497 will accept requests. Possible formats: host, host:port, :port
498 listen_depth
500 Units: connections Default: 1024 Flags: must_restart
501 Listen queue depth.
503 log_hashstring
505 Units: bool Default: off
506 Log the hash string to shared memory log.
508 log_local_address
510 Units: bool Default: off
511 Log the local address on the TCP connection in the SessionOpen
513 shared memory record.
514 lru_interval
516 Units: seconds Default: 2 Flags: experimental
517 Grace period before object moves on LRU list. Objects are only
519 moved to the front of the LRU list if they have not been moved
520 there already inside this timeout period. This reduces the
521 amount of lock operations necessary for LRU list access.
522 max_esi_includes
524 Units: includes Default: 5
525 Maximum depth of esi:include processing.
527 max_restarts
529 Units: restarts Default: 4
530 Upper limit on how many times a request can restart. Be aware
532 that restarts are likely to cause a hit against the backend, so
533 don't increase thoughtlessly.
534 overflow_max
536 Units: % Default: 100 Flags: experimental
537 Percentage permitted overflow queue length.
539 This sets the ratio of queued requests to worker threads, above
541 which sessions will be dropped instead of queued.
542 ping_interval
544 Units: seconds Default: 3 Flags: must_restart
545 Interval between pings from parent to child. Zero will disable
547 pinging entirely, which makes it possible to attach a debugger
548 to the child.
549 pipe_timeout
551 Units: seconds Default: 60
552 Idle timeout for PIPE sessions. If nothing have been received in
554 either direction for this many seconds, the session is closed.
555 prefer_ipv6
557 Units: bool Default: off
558 Prefer IPv6 address when connecting to backends which have both
560 IPv4 and IPv6 addresses.
561 purge_dups
563 Units: bool Default: on
564 Detect and eliminate duplicate purges.
566 rush_exponent
568 Units: requests per request Default: 3 Flags: experimental
569 How many parked request we start for each completed request on
571 the object. NB: Even with the implict delay of delivery, this
572 parameter controls an exponential increase in number of worker
573 threads.
574 saintmode_threshold
576 Units: objects Default: 10 Flags: experimental
577 The maximum number of objects held off by saint mode before no
579 further will be made to the backend until one times out. A
580 value of 0 disables saintmode.
581 send_timeout
583 Units: seconds Default: 600 Flags: delayed
584 Send timeout for client connections. If no data has been sent to
586 the client in this many seconds, the ses‐ sion is closed. See
587 setsockopt(2) under SO_SNDTIMEO for more information.
588 sendfile_threshold
590 Units: bytes Default: -1 Flags: experimental
591 The minimum size of objects transmitted with sendfile.
593 sess_timeout
595 Units: seconds Default: 5
596 Idle timeout for persistent sessions. If a HTTP request has not
598 been received in this many seconds, the session is closed.
599 sess_workspace
601 Units: bytes Default: 65536 Flags: delayed
602 Bytes of HTTP protocol workspace allocated for sessions. This
604 space must be big enough for the entire HTTP protocol header and
605 any edits done to it in the VCL code. Minimum is 1024 bytes.
606 session_linger
608 Units: ms Default: 50 Flags: experimental
609 How long time the workerthread lingers on the session to see if
611 a new request appears right away. If sessions are reused, as
612 much as half of all reuses happen within the first 100 msec of
613 the previous request completing. Setting this too high results
614 in worker threads not doing anything for their keep, setting it
615 too low just means that more sessions take a detour around the
616 waiter.
617 session_max
619 Units: sessions Default: 100000
620 Maximum number of sessions we will allocate before just dropping
622 connections. This is mostly an anti-DoS measure, and setting it
623 plenty high should not hurt, as long as you have the memory for
624 it.
625 shm_reclen
627 Units: bytes Default: 255
628 Maximum number of bytes in SHM log record. Maximum is 65535
630 bytes.
631 shm_workspace
633 Units: bytes Default: 8192 Flags: delayed
634 Bytes of shmlog workspace allocated for worker threads. If too
636 big, it wastes some ram, if too small it causes needless flushes
637 of the SHM workspace. These flushes show up in stats as "SHM
638 flushes due to overflow". Minimum is 4096 bytes.
639 syslog_cli_traffic
641 Units: bool Default: on
642 Log all CLI traffic to syslog(LOG_INFO).
644 thread_pool_add_delay
646 Units: milliseconds Default: 20 Flags: experimental
647 Wait at least this long between creating threads.
649 Setting this too long results in insuffient worker threads.
651 Setting this too short increases the risk of worker thread
653 pile-up.
654 thread_pool_add_threshold
656 Units: requests Default: 2 Flags: experimental
657 Overflow threshold for worker thread creation.
659 Setting this too low, will result in excess worker threads,
661 which is generally a bad idea.
662 Setting it too high results in insuffient worker threads.
664 thread_pool_fail_delay
666 Units: milliseconds Default: 200 Flags: experimental
667 Wait at least this long after a failed thread creation before
669 trying to create another thread.
670 Failure to create a worker thread is often a sign that the end
672 is near, because the process is running out of RAM resources for
673 thread stacks. This delay tries to not rush it on needlessly.
674 If thread creation failures are a problem, check that
676 thread_pool_max is not too high.
677 It may also help to increase thread_pool_timeout and
679 thread_pool_min, to reduce the rate at which treads are
680 destroyed and later recreated.
681 thread_pool_max
683 Units: threads Default: 500 Flags: delayed, experimental
684 The maximum number of worker threads in all pools combined.
686 Do not set this higher than you have to, since excess worker
688 threads soak up RAM and CPU and generally just get in the way of
689 getting work done.
690 thread_pool_min
692 Units: threads Default: 5 Flags: delayed, experimental
693 The minimum number of threads in each worker pool.
695 Increasing this may help ramp up faster from low load situations
697 where threads have expired.
698 Minimum is 2 threads.
700 thread_pool_purge_delay
702 Units: milliseconds Default: 1000 Flags: delayed, experimental
703 Wait this long between purging threads.
705 This controls the decay of thread pools when idle(-ish).
707 Minimum is 100 milliseconds.
709 thread_pool_stack
711 Units: bytes Default: -1 Flags: experimental
712 Worker thread stack size. In particular on 32bit systems you
714 may need to tweak this down to fit many threads into the limited
715 address space.
716 thread_pool_timeout
718 Units: seconds Default: 300 Flags: delayed, experimental
719 Thread idle threshold.
721 Threads in excess of thread_pool_min, which have been idle for
723 at least this long are candidates for purg‐ ing.
724 Minimum is 1 second.
726 thread_pools
728 Units: pools Default: 2 Flags: delayed, experimental
729 Number of worker thread pools.
731 Increasing number of worker pools decreases lock contention.
733 Too many pools waste CPU and RAM resources, and more than one
735 pool for each CPU is probably detrimal to performance.
736 Can be increased on the fly, but decreases require a restart to
738 take effect.
739 thread_stats_rate
741 Units: requests Default: 10 Flags: experimental
742 Worker threads accumulate statistics, and dump these into the
744 global stats counters if the lock is free when they finish a
745 request. This parameters defines the maximum number of requests
746 a worker thread may handle, before it is forced to dump its
747 accumulated stats into the global counters.
748 user Default: .....
750 Flags: must_restart
751 The unprivileged user to run as. Setting this will also set
753 "group" to the specified user's primary group.
754 vcl_trace
756 Units: bool Default: off
757 Trace VCL execution in the shmlog. Enabling this will allow you
759 to see the path each request has taken through the VCL program.
760 This generates a lot of logrecords so it is off by default.
761 waiter Default: default Flags: must_restart, experimental
763 Select the waiter kernel interface.
765 Purge expressions
767 A purge expression consists of one or more conditions. A condition
768 consists of a field, an operator, and an argument. Conditions can be
769 ANDed together with "&&".
770 A field can be any of the variables from VCL, for instance req.url,
772 req.http.host or obj.set-cookie.
773 Operators are "==" for direct comparision, "~" for a regular expression
775 match, and ">" or "<" for size compar‐ isons. Prepending an operator
776 with "!" negates the expression.
777 The argument could be a quoted string, a regexp, or an integer. Inte‐
779 gers can have "KB", "MB", "GB" or "TB" appended for size related
780 fields.
781 Simple example: All requests where req.url exactly matches the string
783 /news are purged from the cache::
784 req.url == "/news"
786 Example: Purge all documents where the name does not end with ".ogg",
788 and where the size of the object is greater than 10 megabytes::
789 req.url !~ "\.ogg$" && obj.size > 10MB
791 Example: Purge all documents where the serving host is "example.com" or
793 "www.example.com", and where the Set- Cookie header received from the
794 backend contains "USERID=1663"::
795 req.http.host ~ "^(www\.)example.com$" && obj.set-cookie ~ "USERID=1663"
797
799 · varnishlog(1)
800 · varnishhist(1)
802 · varnishncsa(1)
804 · varnishstat(1)
806 · varnishtop(1)
808 · vcl(7)
810
812 The varnishd daemon was developed by Poul-Henning Kamp in cooperation
813 with Verdens Gang AS, Linpro AS and Varnish Software.
814 This manual page was written by Dag-Erling Smørgrav with updates by
816 Stig Sandbeck Mathisen ⟨ssm@debian.org⟩
817
819 This document is licensed under the same licence as Varnish itself. See
820 LICENCE for details.
821 · Copyright (c) 2007-2008 Linpro AS
823 · Copyright (c) 2008-2010 Redpill Linpro AS
825 · Copyright (c) 2010 Varnish Software AS
827
829 Dag-Erling Smørgrav, Stig Sandbeck Mathisen, Per Buer
8301.0 2010-05-31 VARNISHD(1)