I wanted to document the support for logging in Matahari, but there
wasn't a good place for that information to go in the manual. I added a
"Getting Started" chapter which is intended to cover installation and
initial configuration tasks.
Signed-off-by: Russell Bryant <rbryant(a)redhat.com>
---
en-US/GettingStarted.xml | 129 ++++++++++++++++++++++++++++++++++++++++++++++
en-US/Matahari.xml | 1 +
2 files changed, 130 insertions(+), 0 deletions(-)
create mode 100644 en-US/GettingStarted.xml
diff --git a/en-US/GettingStarted.xml b/en-US/GettingStarted.xml
new file mode 100644
index 0000000..aefc857
--- /dev/null
+++ b/en-US/GettingStarted.xml
@@ -0,0 +1,129 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Matahari.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="Matahari-GettingStarted">
+ <title>Getting Started</title>
+
+ <para>This chapter covers installation and initial configuration for
+ Matahari. For some additional more advanced configuration topics, see <xref
+ linkend="Matahari-Security" />.</para>
+
+ <section id="GettingStarted-Installation">
+ <title>Installation</title>
+
+ <para>There are a few different ways to install Matahari, depending on the
+ operating system or Linux distribution being used. We aim to get Matahari
+ packaged in various Linux distributions to make installation as easy as
+ possible. If Matahari is not packaged in your Linux distribution, you can
+ fall back to installation from source. For source installation
+ instructures, please see the <ulink
+
url="https://github.com/matahari/matahari/blob/master/README.mkd&quo...
+ included in the Matahari source.</para>
+
+ <section>
+ <title>Linux</title>
+
+ <para>Install Matahari via your Linux distribution's package management
+ system. For example, on Fedora:</para>
+
+ <screen><prompt>#</prompt> <userinput>yum install
matahari</userinput></screen>
+ </section>
+
+ <section>
+ <title>Windows</title>
+
+ <warning>
+ <para>TODO: Document how to install on Windows.</para>
+ </warning>
+ </section>
+ </section>
+
+ <section id="GettingStarted-RunningBroker">
+ <title>Running a Broker</title>
+
+ <para>At this time, the <command>qpidd</command> broker is only
supported
+ on Linux. Matahari comes with a <command>matahari-brokerd</command>
+ wrapper around <command>qpidd</command>. Start it via the include init
+ script or systemd unit.</para>
+
+ <screen><prompt>#</prompt>
<userinput>/etc/init.d/matahari-broker start</userinput></screen>
+
+ <para>or</para>
+
+ <screen><prompt>#</prompt> <userinput>service matahari-broker
start</userinput></screen>
+
+ <para>By defailt, the broker will listen for connections on the Matahari
+ port, <literal>49000</literal>. Customizations can be made by editing
the
+ configuration file. On Fedora, the file is
+ <filename>/etc/sysconfig/matahari-broker</filename>.</para>
+ </section>
+
+ <section>
+ <title>Running Matahari Agents</title>
+
+ <para>How to run Matahari agents differs between Linux and
Windows.</para>
+
+ <section>
+ <title>Linux</title>
+
+ <para>Each Matahari agent can be started via an init script or systemd
+ unit. For example, to start the <literal>Host</literal>
agent:</para>
+
+ <screen><prompt>#</prompt>
<userinput>/etc/init.d/<replaceable>matahari-host</replaceable>
start</userinput></screen>
+
+ <para>or</para>
+
+ <screen><prompt>#</prompt> <userinput>service
<replaceable>matahari-host</replaceable>
start</userinput></screen>
+
+ <para>By default, Matahari agents on Linux assume that there is a broker
+ running locally. To have the agents connect to a different broker, or to
+ set other agent options, edit the configuration file. On Fedora, the
+ file is <filename>/etc/sysconfig/matahari</filename>.</para>
+
+ <section>
+ <title>Logging</title>
+
+ <para>By default, Matahari agents will send log entries to syslog
+ (levels <literal>NOTICE</literal>,
<literal>WARNING</literal>,
+ <literal>ERROR</literal>, <literal>CRITICAL</literal>,
+ <literal>ALERT</literal>, and
<literal>EMERGENCY</literal>). To get
+ more verbose debugging, the agent can be run manually from a terminal
+ with the verbose (<literal>-v</literal>) option, which will enable
+ having log entries sent to <literal>stderr</literal>. For each
+ <literal>-v</literal> passed, the verbosity goes up by one level. A
+ maximum of 3 <literal>-v</literal>s can be passed, which will enable
+ logger levels <literal>INFO</literal>,
<literal>DEBUG</literal>, and
+ <literal>TRACE</literal>.</para>
+
+ <screen><prompt>#</prompt>
<literal>matahari-qmf-<replaceable>host</replaceable>d
-vvv</literal></screen>
+
+ <note>
+ <para>If the verbose option is used to have log output sent to
+ <literal>stderr</literal>, log entries will
<emphasis>not</emphasis>
+ be sent to syslog.</para>
+ </note>
+ </section>
+ </section>
+
+ <section>
+ <title>Windows</title>
+
+ <warning>
+ <para>TODO: Document how to run agents on Windows.</para>
+ </warning>
+
+ <section>
+ <title>Logging</title>
+
+ <para>Logging is currently not supported on Windows. The only way to
+ get log output from an agent running on Windows is to run it in a
+ console with the verbose (<literal>-v</literal>) option. When run in
+ this manner, the log output will be sent to
+ <literal>stderr</literal>.</para>
+ </section>
+ </section>
+ </section>
+</chapter>
diff --git a/en-US/Matahari.xml b/en-US/Matahari.xml
index 8045741..2b7d0c7 100644
--- a/en-US/Matahari.xml
+++ b/en-US/Matahari.xml
@@ -6,6 +6,7 @@
<book>
<xi:include href="Book_Info.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Preface.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="GettingStarted.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Agents.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="CreatingYourOwnAgent.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Security.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
--
1.7.6