Runtime options

Antoine Musso edited this page Jul 10, 2015 · 32 revisions
Clone this wiki locally

These are options you put in /etc/hhvm/config.hdf. We are in the process of killing the .hdf file in favor of a standard php.inisee here for INI settings. This should be considered largely deprecated, though the conversion to INI isn’t quite complete, and there are a handful of niche things you can still only do in hdf.

Configurable 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.

Logging

  Log {
    Level = None (default) | Error | Warning | Info | Verbose
    NoSilencer = false
    AlwaysLogUnhandledExceptions = true
    RuntimeErrorReportingLevel = 8191
    Header = false
    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, 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.

- 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

  }

Error Handling

  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
  }

Resource Limits

  ResourceLimit {
    CoreFileSize = 0          # in bytes
    MaxSocket = 10000         # must be not 0, otherwise HHVM will not start 
    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
  }

Server

  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

    # 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


To further control idle connections, set
ConnectionTimeoutSeconds = 120
This parameter controls how long libevent will timeout a connection after idle on read or write. It takes effect when EnableKeepAlive is enabled. In fastcgi mode, scripts that run longer than this will cause the connection to the web server to drop.

- 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). The cache will be prepared if SourceRoot points to a real file directory and EnableStaticContentFromDisk is true.

- 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
    }

- APC Priming

      PrimeLibrary = filename
      LoadThread = 2
      CompletionKeys {
        * = key name
      }

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
    }

    # 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
  }

Virtual Hosts

  # 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
      }
    }
  }

Administration Server

  AdminServer {
    Port = 8088
    ThreadCount = 1
    Password =  
  }

- If you set password, you should pass it as “auth” GET parameter

Satellite Servers

  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 Server

  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.

Static Content

  StaticFile {
    Extensions {
      bmp = image/bmp
    }
    Generators {
      * = static_resource.php
    }
  }

Note that EnableStaticContentCache must be enabled for the extension mime-types to be recognised. If EnableStaticContentCache is not set, all resources served will be given a text/html content type.

- 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

  Stats = false
  Stats {
    Web = false
    Memory = false
    Malloc = false
    APC = 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 Settings

  Debug {
    FullBacktrace = 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. ServerErrorMessage will send the error message to the output stream.

- RecordInput, ClearInputOnSuccess

With these two settings, we can easily capture an HTTP request in a file that can be replayed with “-m replay” 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.

Sandbox Environment

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.

Debugger Configuration

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

  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 Monitoring

  Http {
    DefaultTimeout = 30         # in seconds
    SlowQueryThreshold = 5000   # in ms, log slow HTTP requests as errors
  }

Mail

  Mail {
    SendmailPath = sendmail -t -i
    ForceExtraParameters =
  }

Tier overwrites

  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.

PHP File Extensions

By default any file with .php in the URL is treated as PHP source code and is passed through to the execution engine for processing. This configuration option allows other file extensions to be treated similarly. Note that .php is automatically treated as such and does not need to be specified in this list.


    PhpFile {
        Extensions {
            phpt = application/x-phpt
            hphp = application/x-hhvm-php
        }
    }

The content type is not used and is just for descriptive purposes.