Skip to content

Runtime options

akrieger edited this page Feb 19, 2012 · 7 revisions

Configurable Options for Compiled Program

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

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

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

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

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

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

- 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
    APCKey = false
    Memcache = 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
    ServerStackTrace = false
    ServerErrorMessage = false
    TranslateSource = false

    RecordInput = false
    ClearInputOnSuccess = true

    ProfilerOutputDir = /tmp

    CoreDumpEmail = email address
    CoreDumpReport = true

    LocalMemcache = false
    MemcacheReadOnly = false
  }

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

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.

HPHPi Settings

  Eval {
    # XHP extension
    EnableXHP = true

    # error level, strict mode is a lot more picky about coding errors
    EnableStrict = false
    StrictLevel = 1     # StrictBasic
    StrictFatal = false

    # experimental, please ignore
    BytecodeInterpreter = false
    DumpBytecode = false
  }

MySQL

  MySQL {
    ReadOnly = false
    Localize = false           # true for native driver that's faster
    ConnectTimeout = 1000      # in ms
    ReadTimeout = 1000         # in ms
    SlowQueryThreshold = 1000  # in ms, log slow queries as errors
    KillOnTimeout = false
  }

- KillOnTimeout

When a query takes 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.