quickstart.xml 5.68 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12
<!--
 - Copyright (C) 2014-2018 Internet Systems Consortium, Inc. ("ISC")
 -
 - This Source Code Form is subject to the terms of the Mozilla Public
 - License, v. 2.0. If a copy of the MPL was not distributed with this
 - file, You can obtain one at http://mozilla.org/MPL/2.0/.
-->

<!-- need this include to make the &keaversion; macro work -->
<!DOCTYPE book [
<!ENTITY % keaversion SYSTEM "version.ent">
%keaversion;
13 14
]>

15
<!-- Converted by db4-upgrade version 1.1 -->
16 17 18 19
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
         xml:id="quickstart">


20
    <title>Quick Start</title>
21 22

    <para>
23
        This section describes the basic steps needed to get Kea up and running.
24 25 26 27
        For further details, full customizations, and troubleshooting, see the
        respective chapters in the Kea guide.
    </para>

28
    <section xml:id="quick-start">
29
      <title>Quick Start Guide for DHCPv4 and DHCPv6 Services</title>
30 31 32 33 34

      <orderedlist>

        <listitem>
          <simpara>
35
            Install required run-time and build dependencies. See <xref linkend="build-requirements"/> for details.
36 37 38 39
          </simpara>
        </listitem>

        <listitem>
40
          <para>
41
            Download Kea source tarball from <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.isc.org/downloads/">ISC.org downloads page</link> or <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://ftp.isc.org/isc/kea/">ISC ftp server</link>.
42 43 44 45 46 47
          </para>
        </listitem>

        <listitem>
          <para>
            Extract the tarball. For example:
48
            <screen>$ <userinput>tar xvzf kea-&keaversion;.tar.gz</userinput></screen>
49
          </para>
50 51 52
        </listitem>

        <listitem>
53
          <para>Go into the source directory and run the configure script:
54
            <screen>$ <userinput>cd kea-&keaversion;</userinput>
55 56 57 58 59 60 61 62 63 64 65
$ <userinput>./configure [your extra parameters]</userinput></screen>
          </para>
        </listitem>

        <listitem>
          <para>Build it:
            <screen>$ <userinput>make</userinput></screen>
          </para>
        </listitem>

        <listitem>
66 67 68
          <para>Install it (by default it will be placed in
          <filename>/usr/local/</filename>,
          so it is likely that you will need root privileges for this step):
69
            <screen># <userinput>make install</userinput></screen>
70 71 72
          </para>
        </listitem>

73 74 75
        <listitem>
          <para>Edit the Kea configuration files which by default are installed in
          the <filename>[kea-install-dir]/etc/kea/</filename> directory. These are:
76 77 78 79
          <filename>kea-dhcp4.conf</filename>, <filename>kea-dhcp6.conf</filename>,
          <filename>kea-dhcp-ddns.conf</filename> and
          <filename>kea-ctrl-agent.conf</filename>, for DHCPv4 server, DHCPv6 server,
          D2 and Control Agent respectively.
80 81 82
          </para>
        </listitem>

83
        <listitem>
84 85 86 87 88
          <para>In order to start the DHCPv4 server in background, run the
          following command (as root):
          <screen># <userinput>keactrl start -s dhcp4</userinput></screen>
          Or run the following command to start DHCPv6 server instead:
          <screen># <userinput>keactrl start -s dhcp6</userinput></screen>
89
          Note that it is also possible to start all servers simultaneously:
90
          <screen>$ <userinput>keactrl start</userinput></screen>
91 92 93 94
          </para>
        </listitem>

        <listitem>
95 96
          <para>Verify that Kea server(s) are running:
          <screen># <userinput>keactrl status</userinput></screen>
97 98
          A server status of "inactive" may indicate a configuration
          error. Please check the log file (by default named
99 100 101 102
          <filename>[kea-install-dir]/var/kea/kea-dhcp4.log</filename>,
          <filename>[kea-install-dir]/var/kea/kea-dhcp6.log</filename>,
          <filename>[kea-install-dir]/var/kea/kea-ddns.log</filename> or
          <filename>[kea-install-dir]/var/kea/kea-ctrl-agent.log</filename>) 
103
          for the details of the error.
104
          </para>
105
        </listitem>
106 107

        <listitem>
108
          <para>
109
            If the server has been started successfully, test that it is
110 111
            responding to DHCP queries and that the client
            receives a configuration from the server; for example, use
112
            the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.isc.org/downloads/DHCP/">ISC DHCP client</link>.
113 114 115 116
          </para>
        </listitem>

        <listitem>
117
          <para>
118
            Stop running the server(s):
119 120
            <screen># <userinput>keactrl stop</userinput></screen>
          </para>
121
        </listitem>
122
      </orderedlist>
123
      <para>
124
        For instructions specific to your system, please read the
125 126
        <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://oldkea.isc.org/wiki/SystemSpecificNotes">system specific notes</link>,
        available on the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://oldkea.isc.org/">Kea web site</link>.
127
      </para>
128

129
      <para>The details of <command>keactrl</command> script usage can be found
130
      in <xref linkend="keactrl"/>.</para>
131 132
    </section>

133
    <section xml:id="quick-start-direct-run">
134 135 136
      <title>Running the Kea Servers Directly</title>
      <para>The Kea servers can be started directly, without the need to use the
      <command>keactrl</command>. To start the DHCPv4 server run the following
137
      command:
138
      <screen># <userinput>kea-dhcp4 -c /path/to/your/kea4/config/file.json</userinput></screen>
139
      Similarly, to start the DHCPv6 server run the following command:
140 141
      <screen># <userinput>kea-dhcp6 -c /path/to/your/kea6/config/file.json</userinput></screen>
    </para>
142 143 144
    </section>

  </chapter>