VirtualBox

Changeset 40130 in vbox for trunk/doc


Ignore:
Timestamp:
Feb 14, 2012 3:17:35 PM (13 years ago)
Author:
vboxsync
Message:

Main/webservice+doc/manual: Add SSL support to the webservice, and also add an optional parameter which ensures the authentication setting is correct. Update manual and SDK reference.

Location:
trunk/doc/manual
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/manual/docbook2latex.xsl

    r37524 r40130  
    1919        by this XSLT (see below).
    2020
    21      Copyright (C) 2006-2010 Oracle Corporation
     21     Copyright (C) 2006-2012 Oracle Corporation
    2222
    2323     This file is part of VirtualBox Open Source Edition (OSE), as
    … …  
    585585            <xsl:with-param name="text" select="$subst6" />
    586586            <xsl:with-param name="replace" select="'~'" />
    587             <xsl:with-param name="with" select="'\~'" />
     587            <xsl:with-param name="with" select="'\textasciitilde '" />
    588588            <xsl:with-param name="disable-output-escaping" select="no" />
    589589          </xsl:call-template>
    … …  
    676676            <xsl:with-param name="text" select="$subst8" />
    677677            <xsl:with-param name="replace" select="'~'" />
    678             <xsl:with-param name="with" select="'\~'" />
     678            <xsl:with-param name="with" select="'\textasciitilde '" />
    679679            <xsl:with-param name="disable-output-escaping" select="no" />
    680680          </xsl:call-template>

  • trunk/doc/manual/en_US/SDKRef.xml

    r39852 r40130  
    293293          binary package for your specific platform. Since the SDK contains
    294294          only platform-independent text files and documentation, the binaries
    295           are instead shipped with the platform-specific packages.</para>
     295          are instead shipped with the platform-specific packages. For this
     296          reason the information how to run it as a service is included in the
     297          VirtualBox documentation.</para>
    296298        </note></para>
    297299
    … …  
    340342            <computeroutput>-p</computeroutput>): This specifies which port to
    341343            bind to on the host and defaults to 18083.</para>
     344          </listitem>
     345
     346          <listitem>
     347            <para><computeroutput>--ssl</computeroutput> (or
     348            <computeroutput>-s</computeroutput>): This enables SSL support.</para>
     349          </listitem>
     350
     351          <listitem>
     352            <para><computeroutput>--keyfile</computeroutput> (or
     353            <computeroutput>-K</computeroutput>): This specifies the file name
     354            containing the server private key and the certificate. This is a
     355            mandatory parameter if SSL is enabled.</para>
     356          </listitem>
     357
     358          <listitem>
     359            <para><computeroutput>--passwordfile</computeroutput> (or
     360            <computeroutput>-a</computeroutput>): This specifies the file name
     361            containing the password for the server private key. If unspecified
     362            or an empty string is specified this is interpreted as an empty
     363            password (i.e. the private key is not protected by a password). If
     364            the file name <computeroutput>-</computeroutput> is specified then
     365            then the password is read from the standard input stream, otherwise
     366            from the specified file. The user is responsible for appropriate
     367            access rights to protect the confidential password.</para>
     368          </listitem>
     369
     370          <listitem>
     371            <para><computeroutput>--cacert</computeroutput> (or
     372            <computeroutput>-c</computeroutput>): This specifies the file name
     373            containing the CA certificate appropriate for the server
     374            certificate.</para>
     375          </listitem>
     376
     377          <listitem>
     378            <para><computeroutput>--capath</computeroutput> (or
     379            <computeroutput>-C</computeroutput>): This specifies the directory
     380            containing several CA certificates appropriate for the server
     381            certificate.</para>
     382          </listitem>
     383
     384          <listitem>
     385            <para><computeroutput>--dhfile</computeroutput> (or
     386            <computeroutput>-D</computeroutput>): This specifies the file name
     387            containing the DH key. Alternatively it can contain the number of
     388            bits of the DH key to generate. If left empty, RSA is used.</para>
     389          </listitem>
     390
     391          <listitem>
     392            <para><computeroutput>--randfile</computeroutput> (or
     393            <computeroutput>-r</computeroutput>): This specifies the file name
     394            containing the seed for the random number generator. If left empty,
     395            an operating system specific source of the seed.</para>
    342396          </listitem>
    343397
    … …  
    370424
    371425          <listitem>
     426            <para><computeroutput>--threads</computeroutput> (or
     427            <computeroutput>-T</computeroutput>): This specifies the maximum
     428            number or worker threads, and defaults to 100. This normally does
     429            not need to be changed.</para>
     430          </listitem>
     431
     432          <listitem>
     433            <para><computeroutput>--keepalive</computeroutput> (or
     434            <computeroutput>-k</computeroutput>): This specifies the maximum
     435            number of requests which can be sent in one web service connection,
     436            and defaults to 100. This normally does not need to be changed.</para>
     437          </listitem>
     438
     439          <listitem>
     440            <para><computeroutput>--authentication</computeroutput> (or
     441            <computeroutput>-A</computeroutput>): This specifies the desired
     442            web service authentication method. If the parameter is not
     443            specified or the empty string is specified it does not change the
     444            authentication method, otherwise it is set to the specified value.
     445            Using this parameter is a good measure against accidental
     446            misconfiguration, as the web service ensures periodically that it
     447            isn't changed.</para>
     448          </listitem>
     449
     450          <listitem>
    372451            <para><computeroutput>--verbose</computeroutput> (or
    373452            <computeroutput>-v</computeroutput>): Normally, the web service
    … …  
    377456            are mapped to internally, which can be useful for debugging client
    378457            programs.</para>
     458          </listitem>
     459
     460          <listitem>
     461            <para><computeroutput>--pidfile</computeroutput> (or
     462            <computeroutput>-P</computeroutput>): Name of the PID file which is
     463            created when the daemon was started.</para>
    379464          </listitem>
    380465
    … …  
    389474            unattended and need to debug problems after they have
    390475            occurred.</para>
     476          </listitem>
     477
     478          <listitem>
     479            <para><computeroutput>--logrotate</computeroutput> (or
     480            <computeroutput>-R</computeroutput>): Number of old log files to
     481            keep, defaults to 10. Log rotation is disabled if set to 0.</para>
     482          </listitem>
     483
     484          <listitem>
     485            <para><computeroutput>--logsize</computeroutput> (or
     486            <computeroutput>-S</computeroutput>): Maximum size of log file in
     487            bytes, defaults to 100MB. Log rotation is triggered if the file
     488            grows beyond this limit.</para>
     489          </listitem>
     490
     491          <listitem>
     492            <para><computeroutput>--loginterval</computeroutput> (or
     493            <computeroutput>-I</computeroutput>): Maximum time interval to be
     494            put in a log file before rotation is triggered, in seconds, and
     495            defaults to one day.</para>
    391496          </listitem>
    392497        </itemizedlist>
    … …  
    445550        use this variable carefully, and only if you fully understand what
    446551        you're doing.</para>
    447       </sect2>
    448 
    449       <sect2>
    450         <title>Solaris host: starting the web service via SMF</title>
    451 
    452         <para>On Solaris hosts, the VirtualBox web service daemon is
    453         integrated into the SMF framework. You can change the parameters, but
    454         don't have to if the defaults below already match your needs:<screen>svccfg -s svc:/application/virtualbox/webservice:default setprop config/host=localhost
    455 svccfg -s svc:/application/virtualbox/webservice:default setprop config/port=18083
    456 svccfg -s svc:/application/virtualbox/webservice:default setprop config/user=root</screen></para>
    457 
    458         <para>If you made any change, don't forget to run the following
    459         command to put the changes into effect immediately:<screen>svcadm refresh svc:/application/virtualbox/webservice:default</screen></para>
    460 
    461         <para>If you forget the above command then the previous settings will
    462         be used when enabling the service. Check the current property settings
    463         with:<screen>svcprop -p config svc:/application/virtualbox/webservice:default</screen></para>
    464 
    465         <para>When everything is configured correctly you can start the
    466         VirtualBox web service with the following command:<screen>svcadm enable svc:/application/virtualbox/webservice:default</screen></para>
    467 
    468         <para>For more information about SMF, please refer to the Solaris
    469         documentation.</para>
    470552      </sect2>
    471553    </sect1>

  • trunk/doc/manual/en_US/user_AdvancedTopics.xml

    r40019 r40130  
    860860        device. Read/write access is also later needed when using the image
    861861        from a virtual machine. On some host platforms (e.g. Windows Vista
    862         and later), raw disk access may be restricted and not permitted by
    863         the host OS in some situations.</para>
     862        and later), raw disk access may be restricted and not permitted by
     863        the host OS in some situations.</para>
    864864
    865865        <para>Just like with regular disk images, this does not automatically
    … …  
    18771877    Development Kit (SDK); please see <xref linkend="VirtualBoxAPI" />. As the
    18781878    client base using this interface is growing, we added start scripts for
    1879     the various operation systems we support. The following describes how to
    1880     use them. Please be aware that the web service is never started automatically
    1881     as a result of a standard installation.<itemizedlist>
    1882         <listitem>
    1883           <para>On Mac OS X, launchd is used. An example configuration file
    1884           can be found in
    1885           <computeroutput>$HOME/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</computeroutput>.
    1886           It can be enabled by changing the
    1887           <computeroutput>Disabled</computeroutput> key from
    1888           <computeroutput>true</computeroutput> to
    1889           <computeroutput>false</computeroutput>. To manually start the
    1890           service use the following command: <screen>launchctl load ~/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</screen>
    1891           For additional information on how launchd services could be
    1892           configured see <literal><ulink
    1893           url="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html">http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html</ulink></literal>.</para>
    1894         </listitem>
    1895         <listitem>
    1896           <para>On Linux, the web service can be automatically started during
    1897             host boot by adding appropriate parameters to the file /etc/default/virtualbox.
    1898             There is one mandatory parameter, VBOXWEB_USER which must be set to
    1899             the user which will later start the VMs.
    1900             <table>
    1901               <title>ignored</title>
    1902               <tgroup cols="2">
    1903                 <tbody>
    1904                   <row>
    1905                     <entry><emphasis role="bold">Parameter</emphasis></entry>
    1906                     <entry><emphasis role="bold">Description</emphasis></entry>
    1907                     <entry><emphasis role="bold">Default</emphasis></entry>
    1908                   </row>
    1909                   <row>
    1910                     <entry>VBOXWEB_HOST</entry>
    1911                     <entry>The host to bind the web service to</entry>
    1912                     <entry>localhost</entry>
    1913                   </row>
    1914                   <row>
    1915                     <entry>VBOXWEB_PORT</entry>
    1916                     <entry>The port to bind the web service to</entry>
    1917                     <entry>18083</entry>
    1918                   </row>
    1919                   <row>
    1920                     <entry>VBOXWEB_TIMEOUT</entry>
    1921                     <entry>Session timeout in seconds; 0 disables timeouts</entry>
    1922                     <entry>300</entry>
    1923                   </row>
    1924                   <row>
    1925                     <entry>VBOXWEB_ CHECK_INTERVAL</entry>
    1926                     <entry>Frequency of timeout checks in seconds</entry>
    1927                     <entry>5</entry>
    1928                   </row>
    1929                   <row>
    1930                     <entry>VBOXWEB_THREADS</entry>
    1931                     <entry>Maximum number of worker threads to run in parallel</entry>
    1932                     <entry>100</entry>
    1933                   </row>
    1934                   <row>
    1935                     <entry>VBOXWEB_KEEPALIVE</entry>
    1936                     <entry>Maximum number of requests before a socket will be closed</entry>
    1937                     <entry>100</entry>
    1938                   </row>
    1939                   <row>
    1940                     <entry>VBOXWEB_LOGFILE</entry>
    1941                     <entry>Name of file to write log to</entry>
    1942                     <entry><emphasis>no file</emphasis></entry>
    1943                   </row>
    1944                   <row>
    1945                     <entry>VBOXWEB_ROTATE</entry>
    1946                     <entry>Number of log files; 0 disables log rotation</entry>
    1947                     <entry>10</entry>
    1948                   </row>
    1949                   <row>
    1950                     <entry>VBOXWEB_LOGSIZE</entry>
    1951                     <entry>Maximum size of a log file in bytes to trigger rotation</entry>
    1952                     <entry>1MB</entry>
    1953                   </row>
    1954                   <row>
    1955                     <entry>VBOXWEB_LOGINTERVAL</entry>
    1956                     <entry>Maximum time interval in seconds to trigger log rotation</entry>
    1957                     <entry>1 day</entry>
    1958                   </row>
    1959                 </tbody>
    1960               </tgroup>
    1961             </table>
    1962           </para>
    1963         </listitem>
    1964       </itemizedlist></para>
     1879    the various operation systems we support. The following sections describe
     1880    how to use them. The VirtualBox web service is never started automatically
     1881    as a result of a standard installation.</para>
     1882
     1883    <sect2 id="vboxwebsrv-linux">
     1884      <title>Linux: starting the webservice via <computeroutput>init</computeroutput></title>
     1885
     1886      <para>On Linux, the web service can be automatically started during
     1887      host boot by adding appropriate parameters to the file
     1888      <computeroutput>/etc/default/virtualbox</computeroutput>.
     1889      There is one mandatory parameter, <computeroutput>VBOXWEB_USER</computeroutput>,
     1890      which must be set to the user which will later start the VMs. The
     1891      paramters in the table below all start with <computeroutput>VBOXWEB_</computeroutput>
     1892      (<computeroutput>VBOXWEB_HOST</computeroutput>,
     1893      <computeroutput>VBOXWEB_PORT</computeroutput> etc.):
     1894      <table>
     1895        <title>ignored</title>
     1896        <tgroup cols="3">
     1897          <tbody>
     1898            <row>
     1899              <entry><emphasis role="bold">Parameter</emphasis></entry>
     1900              <entry><emphasis role="bold">Description</emphasis></entry>
     1901              <entry><emphasis role="bold">Default</emphasis></entry>
     1902            </row>
     1903            <row>
     1904              <entry>USER</entry>
     1905              <entry>The user as which the web service runs</entry>
     1906              <entry></entry>
     1907            </row>
     1908            <row>
     1909              <entry>HOST</entry>
     1910              <entry>The host to bind the web service to</entry>
     1911              <entry>localhost</entry>
     1912            </row>
     1913            <row>
     1914              <entry>PORT</entry>
     1915              <entry>The port to bind the web service to</entry>
     1916              <entry>18083</entry>
     1917            </row>
     1918            <row>
     1919              <entry>SSL_KEYFILE</entry>
     1920              <entry>Server key and certificate file, PEM format</entry>
     1921              <entry></entry>
     1922            </row>
     1923            <row>
     1924              <entry>SSL_PASSWORDFILE</entry>
     1925              <entry>File name for password to server key</entry>
     1926              <entry></entry>
     1927            </row>
     1928            <row>
     1929              <entry>SSL_CACERT</entry>
     1930              <entry>CA certificate file, PEM format</entry>
     1931              <entry></entry>
     1932            </row>
     1933            <row>
     1934              <entry>SSL_CAPATH</entry>
     1935              <entry>CA certificate path</entry>
     1936              <entry></entry>
     1937            </row>
     1938            <row>
     1939              <entry>SSL_DHFILE</entry>
     1940              <entry>DH file name or DH key length in bits</entry>
     1941              <entry></entry>
     1942            </row>
     1943            <row>
     1944              <entry>SSL_RANDFILE</entry>
     1945              <entry>File containing seed for random number generator</entry>
     1946              <entry></entry>
     1947            </row>
     1948            <row>
     1949              <entry>TIMEOUT</entry>
     1950              <entry>Session timeout in seconds; 0 disables timeouts</entry>
     1951              <entry>300</entry>
     1952            </row>
     1953            <row>
     1954              <entry>CHECK_INTERVAL</entry>
     1955              <entry>Frequency of timeout checks in seconds</entry>
     1956              <entry>5</entry>
     1957            </row>
     1958            <row>
     1959              <entry>THREADS</entry>
     1960              <entry>Maximum number of worker threads to run in parallel</entry>
     1961              <entry>100</entry>
     1962            </row>
     1963            <row>
     1964              <entry>KEEPALIVE</entry>
     1965              <entry>Maximum number of requests before a socket will be closed</entry>
     1966              <entry>100</entry>
     1967            </row>
     1968            <row>
     1969              <entry>LOGFILE</entry>
     1970              <entry>Name of file to write log to</entry>
     1971              <entry></entry>
     1972            </row>
     1973            <row>
     1974              <entry>ROTATE</entry>
     1975              <entry>Number of log files; 0 disables log rotation</entry>
     1976              <entry>10</entry>
     1977            </row>
     1978            <row>
     1979              <entry>LOGSIZE</entry>
     1980              <entry>Maximum size of a log file in bytes to trigger rotation</entry>
     1981              <entry>1MB</entry>
     1982            </row>
     1983            <row>
     1984              <entry>LOGINTERVAL</entry>
     1985              <entry>Maximum time interval in seconds to trigger log rotation</entry>
     1986              <entry>1 day</entry>
     1987            </row>
     1988          </tbody>
     1989        </tgroup>
     1990      </table>
     1991      </para>
     1992
     1993      <para>Setting the parameter <computeroutput>SSL_KEYFILE</computeroutput>
     1994      enables the SSL/TLS support. Using encryption is strongly encouraged, as
     1995      otherwise everything (including passwords) is transferred in clear
     1996      text.</para>
     1997    </sect2>
     1998
     1999    <sect2 id="vboxwebsrv-solaris">
     2000      <title>Solaris: starting the web service via SMF</title>
     2001
     2002      <para>On Solaris hosts, the VirtualBox web service daemon is
     2003      integrated into the SMF framework. You can change the parameters, but
     2004      don't have to if the defaults below already match your needs:<screen>svccfg -s svc:/application/virtualbox/webservice:default setprop config/host=localhost
     2005svccfg -s svc:/application/virtualbox/webservice:default setprop config/port=18083
     2006svccfg -s svc:/application/virtualbox/webservice:default setprop config/user=root</screen></para>
     2007
     2008      <para>The table in the previous section showing the parameter names and
     2009      defaults also applies to Solaris. The parameter names must be changed
     2010      to lowercase and a prefix of <computeroutput>config/</computeroutput>
     2011      has to be added, e.g. <computeroutput>config/user</computeroutput> or
     2012      <computeroutput>config/ssl_keyfile</computeroutput>. If you made any
     2013      change, don't forget to run the following command to put the changes into
     2014      effect immediately:<screen>svcadm refresh svc:/application/virtualbox/webservice:default</screen></para>
     2015
     2016      <para>If you forget the above command then the previous settings will
     2017      be used when enabling the service. Check the current property settings
     2018      with:<screen>svcprop -p config svc:/application/virtualbox/webservice:default</screen></para>
     2019
     2020      <para>When everything is configured correctly you can start the
     2021      VirtualBox web service with the following command:<screen>svcadm enable svc:/application/virtualbox/webservice:default</screen></para>
     2022
     2023      <para>For more information about SMF, please refer to the Solaris
     2024      documentation.</para>
     2025    </sect2>
     2026
     2027    <sect2 id="vboxwebsrv-osx">
     2028      <title>Mac OS X: starting the webservice via launchd</title>
     2029
     2030      <para>On Mac OS X, launchd is used to start the VirtualBox webservice. An
     2031      example configuration file can be found in
     2032      <computeroutput>$HOME/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</computeroutput>.
     2033      It can be enabled by changing the
     2034      <computeroutput>Disabled</computeroutput> key from
     2035      <computeroutput>true</computeroutput> to
     2036      <computeroutput>false</computeroutput>. To manually start the
     2037      service use the following command: <screen>launchctl load ~/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</screen>
     2038      For additional information on how launchd services could be
     2039      configured see <literal><ulink
     2040      url="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html">http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html</ulink></literal>.</para>
     2041    </sect2>
    19652042  </sect1>
    19662043
Note: See TracChangeset for help on using the changeset viewer.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette