| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| Copyright 2002-2004 The Apache Software Foundation |
| |
| Licensed under the Apache License, Version 2.0 (the "License"); |
| you may not use this file except in compliance with the License. |
| You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.0//EN" |
| "http://www.oasis-open.org/docbook/xml/simple/1.0/sdocbook.dtd"> |
| <article id="bk_Admin"> |
| <title>BookKeeper Administrator's Guide</title> |
| |
| <subtitle>Setup Guide</subtitle> |
| |
| <articleinfo> |
| <legalnotice> |
| <para>Licensed under the Apache License, Version 2.0 (the "License"); |
| you may not use this file except in compliance with the License. You may |
| obtain a copy of the License at <ulink |
| url="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</ulink>. |
| </para> |
| |
| <para>Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an "AS IS" |
| BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or |
| implied. See the License for the specific language governing permissions |
| and limitations under the License. |
| </para> |
| </legalnotice> |
| |
| <abstract> |
| <para>This document contains information about deploying, administering |
| and mantaining BookKeeper. It also discusses best practices and common |
| problems. |
| </para> |
| <para> As BookKeeper is still a prototype, this article is likely to change |
| significantly over time. |
| </para> |
| </abstract> |
| </articleinfo> |
| |
| <section id="bk_deployment"> |
| <title>Deployment</title> |
| |
| <para>This section contains information about deploying BookKeeper and |
| covers these topics:</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para><xref linkend="bk_sysReq" /></para> |
| </listitem> |
| |
| <listitem> |
| <para><xref linkend="bk_runningBookies" /></para> |
| </listitem> |
| |
| <listitem> |
| <para><xref linkend="bk_zkMetadata" /></para> |
| </listitem> |
| </itemizedlist> |
| |
| <para> The first section tells you how many machines you need. The second explains how to bootstrap bookies |
| (BookKeeper storage servers). The third section explains how we use ZooKeeper and our requirements with |
| respect to ZooKeeper. |
| </para> |
| |
| <section id="bk_sysReq"> |
| <title>System requirements</title> |
| <para> A typical BookKeeper installation comprises a set of bookies and a set of ZooKeeper replicas. The exact number of bookies |
| depends on the quorum mode, desired throughput, and number of clients using this installation simultaneously. The minimum number of |
| bookies is three for self-verifying (stores a message authentication code along with each entry) and four for generic (does not |
| store a message authentication codewith each entry), and there is no upper limit on the number of bookies. Increasing the number of |
| bookies, in fact, enables higher throughput. |
| </para> |
| |
| <para> For performance, we require each server to have at least two disks. It is possible to run a bookie with a single disk, but |
| performance will be significantly lower in this case. Of course, it works with one disk, but performance is significantly lower. |
| </para> |
| |
| <para> For ZooKeeper, there is no constraint with respect to the number of replicas. Having a single machine running ZooKeeper |
| in standalone mode is sufficient for BookKeeper. For resilience purposes, it might be a good idea to run ZooKeeper in quorum |
| mode with multiple servers. Please refer to the ZooKeeper documentation for detail on how to configure ZooKeeper with multiple |
| replicas |
| </para> |
| </section> |
| |
| <section id="bk_runningBookies"> |
| <title>Running bookies</title> |
| <para> |
| To run a bookie, we execute the following command: |
| </para> |
| |
| <para><computeroutput> |
| java -cp .:./zookeeper-<version>-bookkeeper.jar:./zookeeper-<version>.jar:../log4j/apache-log4j-1.2.15/log4j-1.2.15.jar\ |
| -Dlog4j.configuration=log4j.properties org.apache.bookkeeper.proto.BookieServer 3181 /path_to_log_device/\ |
| /path_to_ledger_device/ |
| </computeroutput></para> |
| |
| <para> |
| The parameters are: |
| </para> |
| |
| <itemizedlist> |
| <listitem> |
| <para> |
| Port number that the bookie listens on; |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| Path for Log Device (stores bookie write-ahead log); |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| Path for Ledger Device (stores ledger entries); |
| </para> |
| </listitem> |
| </itemizedlist> |
| |
| <para> |
| Ideally, <computeroutput>/path_to_log_device/ </computeroutput> and <computeroutput>/path_to_ledger_device/ </computeroutput> are each |
| in a different device. |
| </para> |
| </section> |
| |
| <section id="bk_zkMetadata"> |
| <title>ZooKeeper Metadata</title> |
| <para> |
| For BookKeeper, we require a ZooKeeper installation to store metadata, and to pass the list |
| of ZooKeeper servers as parameter to the constructor of the BookKeeper class (<computeroutput> |
| org.apache.bookkeeper.client,BookKeeper</computeroutput>). |
| To setup ZooKeeper, please check the <ulink url="index.html"> |
| ZooKeeper documentation</ulink>. |
| </para> |
| </section> |
| </section> |
| </article> |