-
Notifications
You must be signed in to change notification settings - Fork 0
Runtime options
Note that, in this documentation, we used “*” for names that the system doesn’t care. In reality, one may always use a string or a name to better describe a node’s purpose. Listed values are defaults, unless examples.
You can see program starting options using ./program —help, these include starting as different user after binding to port 80.
Log {
Level = None (default) | Error | Warning | Info | Verbose
NoSilencer = false
AlwaysLogUnhandledExceptions = true
RuntimeErrorReportingLevel = 8191
Header = false
InjectedStackTrace = true
NativeStackTrace = true
MaxMessagesPerRequest = -1
- Level, NoSilencer, AlwaysLogUnhandledExceptions, RuntimeErrorReportingLevel
These settings control different logging levels. NoSilencer means even when silencer operator @ is used, still output errors. Unhandled exceptions are PHP fatal errors, and AlwaysLogUnhandledExceptions will make sure they get logged even if a user’s error handler is installed for them. We also provided RuntimeErrorReportingLevel for compatibility with PHP.
- Header, InjectedStackTrace, NativeStackTrace
These settings control log line formats. Header includes timestamp, process id, thread id, request id (counted from 1 since server starts), message id (counted from 1 since request started) and extra header text from command line option (see util/logger.cpp for implementation).
There are two kinds of stacktraces: (1) C++ stacktrace, which is hex-encoded and printed on every line of logging right after header. These stacktraces can be translated into human readable frames by running “-m translate” with the compiled program. (2) PHP stacktrace from code injection. Generated C++ code injects stacktrace preparation code into every frame of functions and methods. InjectedStackTrace can turn on this PHP stacktrace, which sometimes is cleaner than the C++ stacktrace, which can be turned on and off by NativeStackTrace.
- MaxMessagesPerRequest
Controls maximum number of messages each request can log, in case some pages flood error logs.
If you prefix “filename” with pipe character " | ", e.g. |access.log, logging will be done in access.log and log will be cleared at every startup.
# error log settings
UseLogFile = true
File = filename
# access log settings
AccessLogDefaultFormat = %h %l %u %t "%r" %>s %b
Access {
* {
File = filename
Format = some Apache access log format string
}
* {
File = another filename
Format = some Apache access log format string
}
}
# admin server logging
AdminLog {
File = filename
Format = %h %t %s %U
}
# enable or disable hphp_log() that can be called from PHP code
ApplicationLog = true
# Log aggregator logs one line per several errors, grouped by error's
# stacktraces. It can also save errors to a specified database.
Aggregator = false
Aggregator {
File = filename
Database = [username[:password]@]server[:port][/database]
SleepSeconds = 10 # polling cycle for aggregation
}
}
ErrorHandling {
CallUserHandlerOnFatals = true
NoInfiniteLoopDetection = false
NoInfiniteRecursionDetection = false
MaxStackDepth = 1000
ThrowBadTypeExceptions = false
ThrowNotices = false
NoticeFrequency = 1 # 1 out of these many notices to log
WarningFrequency = 1 # 1 out of these many warnings to log
AssertActive = false
AssertWarning = false
}
ResourceLimit {
CoreFileSize = 0 # in bytes
MaxSocket = 0
SocketDefaultTimeout = 5 # in seconds
MaxRSS = 0
MaxRSSPollingCycle = 0 # in seconds, how often to check max memory
DropCacheCycle = 0 # in seconds, how often to drop disk cache
}
PidFile = pid filename
# $_SERVER['name'] = value
ServerVariables {
name = value
}
# $_ENV['name'] = value
EnvVariables {
name = value
}
Server {
Host = www.default_domain.com
IP = 0.0.0.0
Port = 80
ThreadCount = 50
SourceRoot = path to source files and static contents
IncludeSearchPaths {
* = some path
* = another path
}
RequestTimeoutSeconds = -1
RequestMemoryMaxBytes = -1
# Recommend to turn this on to avoid memory leaks and to enable warmup
# document features.
EnableMemoryManager = false
# Only for debugging memory problems. When turned on, server will report
# SmartAllocator's usage for each thread to stdout.
CheckMemory = false
# If ServerName is not specified for a virtual host, use prefix + this
# suffix to compose one
DefaultServerNameSuffix = default_domain.com
# Forcing $_SERVER['SERVER_NAME'] to come from request header
ForceServerNameToHeader = false
# startup options
TakeoverFilename = filename # for port takeover between server instances
DefaultDocument = index.php
StartupDocument = filename
WarmupDocument = filename
RequestInitFunction = function_name
ThreadDocuments {
* = somedoc.php
* = another.php
}
ErrorDocument404 = 404.php
FatalErrorMessage = some string
# shutdown options
GracefulShutdownWait = 0 # in seconds
HarshShutdown = true
EvilShutdown = true
DanglingWait = 0
- GracefulShutdownWait, HarshShutdown, EvilShutdown
Graceful shutdown will try admin /stop command and it waits for number of seconds specified by GracefulShutdownWait. Harsh shutdown looks for pid file and try to kill that process. Evil shutdown kills anything listening on the server port it’s trying to grab.
- DanglingWait
How long to wait for dangling server to respond.
# HTTP settings
GzipCompressionLevel = 3
EnableMagicQuotesGpc = false
EnableKeepAlive = true
EnableEarlyFlush = true
ForceChunkedEncoding = false
MaxPostSize = 8 # in MB
LibEventSyncSend = true
ResponseQueueCount = 0
- EnableEarlyFlush, ForceChunkedEncoding
EnableEarlyFlush allows chunked encoding responses, and ForceChunkedEncoding will only send chunked encoding responses, unless client doesn’t understand.
- LibEventSyncSend, ResponseQueueCount
These are fine tuning options for libevent server. LibEventSyncSend allows response packets to be sent directly from worker thread, normally resulting in faster server responses. ResponseQueueCount specifies how many response queues to use for sending.
# static contents
FileCache = filename
EnableStaticContentCache = true
EnableStaticContentFromDisk = true
ExpiresActive = true
ExpiresDefault = 2592000
DefaultCharsetName = UTF-8
- EnableStaticContentCache, EnableStaticContentFromDisk
A static content cache creates one single file from all static contents, including css, js, html, images and any other non-PHP files (or even PHP files, if CachePHPFile is turned on for compiler options). Normally this is prepared by compiler at compilation time, but it can also be prepared at run-time, if SourceRoot points to real file directory and EnableStaticContentFromDisk is true. Otherwise, use FileCache to point to the static content cache file created by the compiler.
- ExpiresActive, ExpiresDefault, DefaultCharsetName
These control static content’s response headers.
# file access control
SafeFileAccess = false
FontPath = where to look for font files
AllowedDirectories {
* = /tmp
}
AllowedFiles {
* = specific file to allow
}
APC {
EnableApc = true
UseSharedMemory = false
SharedMemorySize = 1024 # in MB
- UseSharedMemory
When off, APC will use regular process memory for faster access, but only limited to single process. Shared memory model allows sharing between two or more processes, but it has SharedMemorySize as upper limit.
PrimeLibrary = filename
LoadThread = 2
CompletionKeys {
* = key name
}
- APC Priming
There is a way to prepare APC items in dry format, serialized in binary files, and these files can be loaded (or “primed”) extremely fast at startup time. To prepare these .cpp files, check bin/apc_sample_serializer.php for one way of doing it. Once prepared, we can compiled them into .so that can be loaded through PrimeLibrary option. The loading can be done in parallel with LoadThread count of threads. Once loading is done, it can write to APC with some specified keys in CompletionKeys to tell web application about priming.
TableType = hash (default) | lfu | concurrent
LockType = readwritelock | mutex
UseLockedRefs = false
- TableType, LockType, UseLockedRefs
Recommend to use “concurrent”, the fastest with least locking. “lfu” is experimental for now and it may have bugs. When “concurrent”, LockType doesn’t matter. UseLockedRefs uses mutexes than atomic numbers for APC item’s reference counting, so it’s recommended to turn off.
ExpireOnSets = false
PurgeFrequency = 4096
- ExpireOnSets, PurgeFrequency
ExpireOnSets turns on item purging on expiration, and it’s only done once per PurgeFrequency of sets.
KeyMaturityThreshold = 20
MaximumCapacity = 0
KeyFrequencyUpdatePeriod = 1000 # in number of accesses
- KeyMaturityThreshold, MaximumCapacity, KeyFrequencyUpdatePeriod
These are experimental LFU settings.
}
# DNS cache
DnsCache {
Enable = false
TTL = 600 # in seconds
KeyMaturityThreshold = 20
MaximumCapacity = 0
KeyFrequencyUpdatePeriod = 1000
}
# Light process has very little forking cost, because they are pre-forked
# Recommend to turn it on for faster shell command execution.
LightProcessFilePrefix = ./lightprocess
LightProcessCount = 0
# RTTI profiling settings. Experimental.
RTTIDirectory = /tmp/
EnableCliRTTI = false
}
# default IpBlockMap that applies to all URLs, if exists
IpBlockMap {
* {
Location = /url
AllowFirst = false
Ip {
Allow {
* = 127.0.0.1
* = 192.0.0.0/8
}
Deny {
* = 192.1.0.0
}
}
}
}
VirtualHost {
* {
Disabled = false
Prefix = prefix.
Pattern = regex pattern
PathTranslation = html
ServerName =
ServerVariables {
name = value
}
RewriteRules {
* {
pattern = regex pattern same as Apache's
to = target format same as Apache's
qsa = false
redirect = 0 (default: off) | 302 | 301 | other status code
conditions {
* {
pattern = regex pattern to match
type = host | request
negate = false
}
}
}
}
IpBlockMap {
# in same format as the IpBlockMap example above
}
}
}
AdminServer {
Port = 8088
ThreadCount = 1
Password =
}
Satellites {
* {
Type = RPCServer | InternalPageServer | DanglingPageServer
Port = 9999
ThreadCount = 5
# only for RPCServer
MaxRequest = 500
MaxDuration = 120 # in seconds
TimeoutSeconds = 30 # default to RequestTimeoutSeconds
WarmupDocument = lib/warmup.php
RequestInitFunction = on_init
Password = authentication
# only for InternalPageServer
BlockMainServer = true
URLs {
* = pattern
}
}
}
- RPCServer, DanglingPageServer
Please refer to their documentations for more details.
- Internal Page Server
Serves internal pages over a private port. These pages will become unavailable to main HTTP port if BlockMainServer is turned on. Use URLs to specify regex patterns for pages to server over this port.
Xbox {
ServerInfo {
ThreadCount = 0
Port = 0
MaxRequest = 500
MaxDuration = 120
WarmupDocument =
RequestInitFunction =
}
ProcessMessageFunc = xbox_process_message
DefaultLocalTimeoutMilliSeconds = 500
DefaultRemoteTimeoutSeconds = 5
}
- Xbox Server
An xbox server provides cross-machine communication, similar to a message queuing system. It also allows local processing of messages, then working as a multithreading facility for PHP execution. More documentation will be coming for xbox applications.
PageletServer {
ThreadCount = 0
}
- Pagelet Server
A pagelet server is essentially the same as local CURL, except it’s more efficient. This allows parallel execution of a web page, preparing two panels or iframes at the same time.
Proxy {
Origin = the server to proxy to
Retry = 3
# serve these URLs and proxy all others, trumping ProxyURLs settings
ServeURLs = false
ServeURLs {
* = urls not to proxy
}
# proxy these URLs
ProxyURLs = false
ProxyURLs {
* = urls to proxy
}
# proxy these patterns
ProxyPatterns {
* = patterns to proxy
}
# proxy this percentage of pages
Percentage = 0
}
- ServeURLs, ProxyURLs
Please note that these two settings are mutually exclusive, and you may turn on just one. When ProxyURLs is on, you may choose to use ProxyURLs, ProxyPatterns or Percentage or any combination of them to specify how it should be proxied.
StaticFile {
Extensions {
bmp = image/bmp
}
Generators {
* = static_resource.php
}
}
- Generators
In addition to Static Content Cache, we also support Dynamic Content Cache. If static_resource.php generates identical files given the same HTTP input, it can be listed under Generators, so its generated content can be cached for next requests.
Stats = false
Stats {
Web = false
Memory = false
Malloc = false
APC = false
APCKey = false
SQL = false
XSL = xsl filename
XSLProxy = url to get the xsl file
SlotDuration = 600 # in seconds
MaxSlot = 72 # 10 minutes x 72 = 12 hours
}
Debug {
FullBacktrace = false
ServerStackTrace = false
ServerErrorMessage = false
TranslateSource = false
RecordInput = false
ClearInputOnSuccess = true
ProfilerOutputDir = /tmp
CoreDumpEmail = email address
CoreDumpReport = true
}
- FullBacktrace, ServerStackTrace, ServerErrorMessage, TranslateSource
These settings turn on error messages in HTTP responses with detailed stacktrace information. TranslateSource will translate C++ file and line numbers into original PHP file and line numbers.
- RecordInput, ClearInputOnSuccess
With these two settings, we can easily capture an HTTP request in a file that can be replayed with “-m replay” from the compiled program at command line. We can easily gdb that way to debug any problems. Watch error log for recorded file’s location. ClearInputOnSuccess can automatically delete requests that had 200 responses and it’s useful to capture 500 errors on production without capturing good responses.
A sandbox has pre-defined setup that maps some directory to be source root of a web server, hence eliminating a lot of setups.
Sandbox {
SandboxMode = false
Pattern = regex pattern with at least one capture group, eg. www.([^-]*(-[^-]*)?).facebook.com
Home = /home
ConfFile = .hphp
ServerVariables {
name = value
}
}
- Sandbox Configuration
The capture group in the regex defines the ‘user’ and the ‘sandbox’ to use. The group is split on the ‘-’ character, and the first token is the ‘user’, the second (optional) token is the sandbox for that user. So, for example, www.bovik-test.facebook.com would be interpreted to mean “use the ‘test’ sandbox of user ‘bovik’”.
Sandboxes are defined by a configuration file per user. In the example above, the configuration file would be located at /home/bovik/.hphp. This configuration file as the following format:
[sandbox].path = path # relative to user's homedir, eg. www-test
[sandbox].log = path
[sandbox].accesslog = path
“path” points to PHP source files. “log” points to error log location and “accesslog” points to access log location.
In the event that the ‘sandbox’ token is omitted from the url (eg. www.bovik.facebook.com), then the sandbox name ‘default’ is used. If ‘default’ were substituted for [sandbox] in the configuration above, then loading www.bovik.facebook.com would serve files out of /home/bovik/www-test. Depending on your configuration, you can also get files served from the directory where hphp is run.
- Machine Sharing
The benefit is, same server can have one “Sandbox” configuration, and many users can use the same machine serving their own source files.
By default, HHVM does not listen for connections from the HipHop Debugger (hphpd). To enable this you need to first setup the sandbox environment described above, then add the following to your config:
Eval.Debugger {
EnableDebugger = true
EnableDebuggerServer = true
Port = 8089
DefaultSandboxPath = path to source files, probably the same as Server.SourceRoot
}
This will cause HHVM to start a debugger server, and you should see an entry in the log indicating the debugger server has started before the entry about all servers having been started.
MySQL {
ReadOnly = false
ConnectTimeout = 1000 # in ms
ReadTimeout = 1000 # in ms
SlowQueryThreshold = 1000 # in ms, log slow queries as errors
KillOnTimeout = false
}
- KillOnTimeout
When a query takes a long time to execute on server, client has a chance to kill it to avoid extra server cost by turning on KillOnTimeout.
Http {
DefaultTimeout = 30 # in seconds
SlowQueryThreshold = 5000 # in ms, log slow HTTP requests as errors
}
Mail {
SendmailPath = sendmail -t -i
ForceExtraParameters =
}
Tiers {
* {
machine = /regex pattern/
overwrite {
# any config settings described in this documentation
}
}
}
This feature allows a machine to overwrite configurations just by matching machine names with specified regex pattern. This block of configuration can appear at any location of the file, even at top.