1 <h2>Configurable Options for Compiled Program</h2>
3 Note that, in this documentation, we used "*" for names that the system doesn't
4 care. In reality, one may always use a string or a name to better describe a
5 node's purpose. Listed values are defaults, unless examples.
10 Level = None (default) | Error | Warning | Info | Verbose
12 AlwaysLogUnhandledExceptions = false
13 RuntimeErrorReportingLevel = 8191
14 ForceErrorReportingLevel = 0
17 NativeStackTrace = true
18 MaxMessagesPerRequest = -1
20 - Level, NoSilencer, AlwaysLogUnhandledExceptions, RuntimeErrorReportingLevel,
21 ForceErrorReportingLevel
23 These settings control different logging levels. NoSilencer means even when
24 silencer operator @ is used, still output errors. Unhandled exceptions are
25 PHP fatal errors, and AlwaysLogUnhandledExceptions will make sure they get
26 logged even if a user's error handler is installed for them. We also provided
27 RuntimeErrorReportingLevel for compatibility with PHP. ForceErrorReportingLevel
28 is a bitmask that will be ORed with RuntimeErrorReportingLevel to determine the
29 actual error reporting level.
31 - Header, NativeStackTrace
33 These settings control log line formats. Header includes timestamp, process id,
34 thread id, request id (counted from 1 since server starts), message id
35 (counted from 1 since request started) and extra header text from command line
36 option (see util/logger.cpp for implementation).
38 There are two kinds of stacktraces: (1) C++ stacktrace, which is hex-encoded
39 and printed on every line of logging right after header. These stacktraces can
40 be translated into human readable frames by running "-m translate" with the
41 compiled program. (2) PHP stacktrace from code injection. Generated C++ code
42 injects stacktrace preparation code into every frame of functions and methods.
46 This setting controls logging of potentially malicious headers. If
47 HeaderMangle is greater than 0, then HipHop will log one in every n
48 requests where a header collision has occurred. Such collisions
49 almost certainly indicate a malicious attempt to set headers which are
50 either set or filtered by a proxy.
52 - MaxMessagesPerRequest
54 Controls maximum number of messages each request can log, in case some pages
63 AccessLogDefaultFormat = %h %l %u %t \"%r\" %>s %b
67 Format = some Apache access log format string
70 File = another filename
71 Format = some Apache access log format string
75 # admin server logging
85 # Bitmask of error constants to upgrade to E_USER_ERROR. Only E_WARNING,
86 # E_USER_WARNING, E_NOTICE, and E_USER_NOTICE are supported.
87 UpgradeLevel = 0 (default)
88 CallUserHandlerOnFatals = false
89 NoInfiniteRecursionDetection = false
90 NoticeFrequency = 1 # 1 out of these many notices to log
91 WarningFrequency = 1 # 1 out of these many warnings to log
97 CoreFileSize = 0 # in bytes
99 SocketDefaultTimeout = 60 # in seconds
101 MaxRSSPollingCycle = 0 # in seconds, how often to check max memory
102 DropCacheCycle = 0 # in seconds, how often to drop disk cache
104 SerializationSizeLimit = 0
109 PidFile = pid filename
111 # $_SERVER['name'] = value
116 # $_ENV['name'] = value
122 Host = www.default_domain.com
125 Type = proxygen | fastcgi
127 ThreadDropCacheTimeoutSeconds = 0
128 ThreadJobLIFO = false
130 SourceRoot = path to source files and static contents
135 # Recommend to turn this on when all the file paths in the file invoke
136 # table are relative for faster dynamic file inclusion.
137 AlwaysUseRelativePath = false
139 RequestTimeoutSeconds = -1
140 RequestMemoryMaxBytes = 0
142 # maximum POST Content-Length
144 # maximum memory size for image processing
145 ImageMemoryMaxBytes = Upload.UploadMaxFileSize * 2
147 # If ServerName is not specified for a virtual host, use prefix + this
148 # suffix to compose one. If "Pattern" was specified, matched pattern,
149 # either by parentheses for the first match or without parentheses for
150 # the whole pattern, will be used as prefix for DefaultServerNameSuffix.
151 DefaultServerNameSuffix = default_domain.com
153 # Forcing $_SERVER['SERVER_NAME'] to come from request header
154 ForceServerNameToHeader = false
156 # Print file paths traversed onto the 404 page
160 TakeoverFilename = filename # for port takeover between server instances
161 DefaultDocument = index.php
162 StartupDocument = filename
163 RequestInitFunction = function_name
164 RequestInitDocument = filename
165 ErrorDocument404 = 404.php
166 ErrorDocument500 = 500.php
167 FatalErrorMessage = some string
170 GracefulShutdownWait = 0 # in seconds
177 SSLCertificateFile = <certificate file> # similar to apache
178 SSLCertificateKeyFile = <certificate file> # similar to apache
180 - GracefulShutdownWait, HarshShutdown, EvilShutdown
182 Graceful shutdown will try admin /stop command and it waits for number of
183 seconds specified by GracefulShutdownWait. Harsh shutdown looks for pid file
184 and try to kill that process. Evil shutdown kills anything listening on the
185 server port it's trying to grab.
188 GzipCompressionLevel = 3
190 # force response to be compressed, even if there isn't accept-encoding
191 URL = # if URL perfectly matches this
192 Cookie = # if this cookie is present: "name" or "name=value"
193 Param = # if this parameter in query string is present
195 EnableKeepAlive = true
196 EnableOutputBuffering = false
198 ImplicitFlush = false
199 EnableEarlyFlush = true
200 ForceChunkedEncoding = false
201 MaxPostSize = 8 # in MB
203 To further control idle connections, set
204 ConnectionTimeoutSeconds = <some value>
205 This parameter controls how long the server will timeout a connection after
206 idle on read or write. It takes effect when EnableKeepAlive is enabled.
208 - EnableEarlyFlush, ForceChunkedEncoding
210 EnableEarlyFlush allows chunked encoding responses, and ForceChunkedEncoding
211 will only send chunked encoding responses, unless client doesn't understand.
215 EnableStaticContentFromDisk = true
217 ExpiresDefault = 2592000
218 DefaultCharsetName = UTF-8
220 - EnableStaticContentFromDisk
222 A static content cache creates one single file from all static contents,
223 including css, js, html, images and any other non-PHP files (or even PHP files,
224 if CachePHPFile is turned on for compiler options). Normally this is prepared
225 by compiler at compilation time, but it can also be prepared at run-time, if
226 SourceRoot points to real file directory and EnableStaticContentFromDisk is
227 true. Otherwise, use FileCache to point to the static content cache file
228 created by the compiler.
230 NOTE: the FileCache should be set with absolute path
232 - ExpiresActive, ExpiresDefault, DefaultCharsetName
234 These control static content's response headers. DefaultCharsetName is also
235 used for PHP responses in case no other charset has been set explicitly.
237 # file access control
238 SafeFileAccess = false
239 FontPath = where to look for font files
244 * = specific file to allow
247 # files with these extensions cannot be executed
248 ForbiddenFileExtensions {
254 PrimeLibrary = filename
262 There is a way to prepare APC items in dry format, serialized in binary files,
263 and these files can be loaded (or "primed") extremely fast at startup time.
264 To prepare these .cpp files, check apc_sample_serializer.php for one way
265 of doing it. Once prepared, we can compiled them into .so that can be loaded
266 through PrimeLibrary option. The loading can be done in parallel with
267 LoadThread count of threads. Once loading is done, it can write to APC with
268 some specified keys in CompletionKeys to tell web application about priming.
270 TableType = concurrent (default)
274 Recommend to use "concurrent", the fastest with least locking, and since its
275 the only implemented table type. (The option remains for future use if we
276 add other apc implementations).
279 PurgeFrequency = 4096
281 - ExpireOnSets, PurgeFrequency
283 ExpireOnSets turns on item purging on expiration, and it's only done once per
284 PurgeFrequency of sets.
286 KeyMaturityThreshold = 20
288 KeyFrequencyUpdatePeriod = 1000 # in number of accesses
290 - KeyMaturityThreshold, MaximumCapacity, KeyFrequencyUpdatePeriod
292 These are experimental LFU settings.
299 TTL = 600 # in seconds
302 # Light process has very little forking cost, because they are pre-forked
303 # Recommend to turn it on for faster shell command execution.
304 LightProcessFilePrefix = ./lightprocess
305 LightProcessCount = 0
309 UploadMaxFileSize = 100 # Size in MB
311 EnableFileUploads = true
312 EnableUploadProgress = false
313 Rfc1867Freq = 262144 # 256K
314 Rfc1867Prefix = vupload_
315 Rfc1867Name = video_ptoken
321 # default IpBlockMap that applies to all URLs, if exists
342 Pattern = regex pattern
343 PathTranslation = html
344 CheckExistenceBeforeRewrite = true
352 pattern = regex pattern same as Apache's
353 to = target format same as Apache's
355 redirect = 0 (default: off) | 302 | 301 | other status code
359 pattern = regex pattern to match
360 type = host | request
368 # in same format as the IpBlockMap example above
371 # Remove certain query string parameters from access log.
374 # regex pattern to match a URL
375 url = (empty means matching all URLs)
377 # names of parameters to remove from query string
382 # alternatively, use regex pattern to replace with empty string.
383 pattern = (empty means hiding entire query string)
385 # optionally, specify what values to replace with
386 value = (by default it's empty, removing the query parameter)
392 - CheckExistenceBeforeRewrite
394 With this setting, rewrite rules will not be applied for files that exist in
395 the original path. This is the default behavior. Set this to false if one wants
396 to block access to certain files (ex. .htaccess.)
398 = Administration Server
410 Type = RPCServer | InternalPageServer
417 MaxDuration = 120 # in seconds
418 TimeoutSeconds = 30 # default to RequestTimeoutSeconds
419 RequestInitFunction = on_init
420 RequestInitDocument = filename
421 Password = authentication
423 # only for InternalPageServer
424 BlockMainServer = true
433 Please refer to its documentation for more details.
435 - Internal Page Server
437 Serves internal pages over a private port. These pages will become unavailable
438 to main HTTP port if BlockMainServer is turned on. Use URLs to specify regex
439 patterns for pages to server over this port.
447 RequestInitFunction =
448 RequestInitDocument =
450 ProcessMessageFunc = xbox_process_message
451 DefaultLocalTimeoutMilliSeconds = 500
452 DefaultRemoteTimeoutSeconds = 5
457 An xbox server provides cross-machine communication, similar to a message
458 queuing system. It also allows local processing of messages, then working as
459 a multithreading facility for PHP execution. More documentation will be coming
460 for xbox applications.
468 A pagelet server is essentially the same as local CURL, except it's more
469 efficient. This allows parallel execution of a web page, preparing two panels
470 or iframes at the same time.
475 Origin = the server to proxy to
478 # serve these URLs and proxy all others, trumping ProxyURLs settings
481 * = urls not to proxy
489 # proxy these patterns
491 * = patterns to proxy
493 # proxy this percentage of pages
497 - ServeURLs, ProxyURLs
499 Please note that these two settings are mutually exclusive, and you may turn on
500 just one. When ProxyURLs is on, you may choose to use ProxyURLs, ProxyPatterns
501 or Percentage or any combination of them to specify how it should be proxied.
510 * = static_resource.php
514 pattern = .*\.(dll|exe)
516 * = Content-Disposition: attachment
524 In addition to Static Content Cache, we also support Dynamic Content Cache. If
525 static_resource.php generates identical files given the same HTTP input, it
526 can be listed under Generators, so its generated content can be cached for
542 XSLProxy = url to get the xsl file
544 SlotDuration = 600 # in seconds
545 MaxSlot = 72 # 10 minutes x 72 = 12 hours
565 ServerErrorMessage = false
568 ClearInputOnSuccess = true
570 ProfilerOutputDir = /tmp
572 CoreDumpEmail = email address
573 CoreDumpReport = true
574 CoreDumpReportDirectory = /tmp
576 StackTraceTimeout = 0
581 This setting turns on error messages in HTTP responses.
583 - RecordInput, ClearInputOnSuccess
585 With these two settings, we can easily capture an HTTP request in a file that
586 can be replayed with "-m replay" from the compiled program at command line.
587 We can easily gdb that way to debug any problems. Watch error log for recorded
588 file's location. ClearInputOnSuccess can automatically delete requests that
589 had 200 responses and it's useful to capture 500 errors on production without
590 capturing good responses.
594 This specifies the maximum number of seconds spent for generating a stack trace
595 when hhvm is crashed. The default is 0 which means no timeout. This can be set
596 to prevent from deadlocks in the backtrace handler.
600 There are options for APC size profiling. If enabled, APC overall size will be
601 updated every time a store or delete happens. This allows querying apc stats
602 on admin port. 'CountPrime' controls whether size stats includes primed keys.
603 'Group' controls whether stats break-down by key groups get profiled.
604 'SpecialPrefix' and 'SpecialMiddle' are used for aggregating some keys groups.
605 'Individual' controls whether size profiling is enabled for each key, which
606 could incur some space overhead. 'FetchStats' can be enabled to also profile
607 apc_fetch, which further increases time overhead.
608 'FetchStats' implies 'Individual', and 'Individual' implies 'Group'
610 = Sandbox Environment
612 A sandbox has pre-defined setup that maps some directory to be source root of
613 a web server, hence eliminating a lot of setups.
617 Pattern = www.[user]-[sandbox].[machine].facebook.com
626 - Sandbox Configuration
628 First, pick a name. "default" has special meaning, then URL would be
629 www.[user].[machine].facebook.com. Say the name is "sandbox", the configuration
632 [sandbox].path = path
634 [sandbox].accesslog = path
636 "path" points to PHP source files. "log" points to error log location and
637 "accesslog" points to access log location.
639 == Debugger Configuration
641 By default, HHVM does not listen for connections from the HipHop
642 Debugger (hphpd). To enable this you need to first setup the sandbox
643 environment described above, then add the following to your config:
646 EnableDebugger = true
647 EnableDebuggerServer = true
649 DefaultSandboxPath = path to source files, similar to Server.SourceRoot
652 This will cause HHVM to start a debugger server, and you should see an
653 entry in the log indicating the debugger server has started before the
654 entry about all servers having been started.
658 The benefit is, same server can have one "Sandbox" configuration, and many
659 users can use the same machine serving their own source files.
666 EnableHipHopSyntax = false
667 EnableHipHopExperimentalSyntax = false
669 EnableShortTags = true # is <? allowed
670 EnableAspTags = false # is <% %> allowed
671 EnableXHP = true # XHP extension
672 NativeXHP = true # Use HPHP to directly handle XHP
674 VMStackElms = 16384 # Maximum stack size
678 EnableDebugger = false
679 EnableDebuggerServer = false
692 TimeoutsUseWallTime = true
693 CheckFlushOnUserClose = true
695 # Causes HHVM to disallow constructs that are unavailable when Repo.Authoritative
696 # is active, without requiring you to run in Repo.Authoritative.
697 AuthoritativeMode = true
699 # experimental, please ignore
700 BytecodeInterpreter = false
702 RecordCodeCoverage = false
703 CodeCoverageOutputFile =
708 Determines whether or not to follow symlinks (and, from a performance
709 standpoint, make the associated realpath() calls needed) when resolving
710 includes/requires and loading code. This is enabled by default for parity with
711 the reference implementation. If not needed for a particular application and/or
712 configuration, disable this when tuning.
714 - TimeoutsUseWallTime
716 Determines whether or not to interpret set_time_limit timeouts as wall time or
717 CPU time (which the reference implementation uses.) Defaults to wall time.
719 - CheckFlushOnUserClose
721 Determines whether or not close() for user streams (registered by
722 stream_wrapper_register) will consider the return value of the implicit call to
723 flush() when calculating its return value.
729 ConnectTimeout = 1000 # in ms
730 ReadTimeout = 1000 # in ms
731 WaitTimeout = -1 # in ms, -1 means "don't set"
732 SlowQueryThreshold = 1000 # in ms, log slow queries as errors
733 KillOnTimeout = false
734 Socket = # Default location to look for mysql.sock
740 When a query takes long time to execute on server, client has a chance to
741 kill it to avoid extra server cost by turning on KillOnTimeout.
745 Zend returns strings and NULL only for MySQL results, not integers or floats.
746 HHVM return ints (and, sometimes, actual doubles). This behavior can be
747 disabled by setting TypedResults to false.
752 DefaultTimeout = 30 # in seconds
753 SlowQueryThreshold = 5000 # in ms, log slow HTTP requests as errors
759 SendmailPath = sendmail -t -i
760 ForceExtraParameters =
766 BacktraceLimit = 100000
767 RecursionLimit = 100000
772 The number of patterns which can be stored in the PCRE cache.
776 May be "static", for a very fast cache which never evicts, "lru", for a cache
777 which evicts the least-recently used item when full, or "scalable" for a cache
778 which is slightly slower than "lru" at low concurrency but much faster for a
779 high-concurrency tight-loop workload.
783 - Eval.PCREExpireInterval
785 If Eval.PCRECacheType is set to "static", then setting this to an integer
786 number of seconds will cause the cache to be regularly cleared after the
787 specified number of seconds.
789 For "lru" and "scalable" type caches, this is not necessary and not supported.
795 machine = /regex pattern/
797 # any config settings described in this documentation
802 This feature allows a machine to overwrite configurations just by matching
803 machine names with specified regex pattern. This block of configuration can
804 appear at any location of the file, even at top.
806 = PHP File Extensions
808 By default any file with .php in the URL is treated as PHP source code and is
809 passed through to the execution engine for processing. This configuration option
810 allows other file extensions to be treated similarly. Note that .php is
811 automatically treated as such and does not need to be specified in this list.
815 phpt = application/x-phpt
816 hphp = application/x-hhvm-php
820 The content type is not used and is just for descriptive purposes.