<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Declaring and reading configuration details</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="PowerDNS manual"
HREF="index.html"><LINK
REL="UP"
TITLE="Backend writers' guide"
HREF="backend-writers-guide.html"><LINK
REL="PREVIOUS"
TITLE="Reporting errors"
HREF="backend-error-reporting.html"><LINK
REL="NEXT"
TITLE="Read/write slave-capable backends"
HREF="rw-backends.html"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>PowerDNS manual</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="backend-error-reporting.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Appendix C. Backend writers' guide</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="rw-backends.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="BACKEND-CONFIGURATION-DETAILS"
>C.3. Declaring and reading configuration details</A
></H1
><P
> It is highly likely that a backend needs configuration details. On launch, these parameters need to be declared with PDNS so it knows it
should accept them in the configuration file and on the commandline. Furthermore, they will be listed in the output of
<B
CLASS="COMMAND"
>--help</B
>.
</P
><P
> Declaring arguments is done by implementing the member function <CODE
CLASS="FUNCTION"
>declareArguments()</CODE
> in the factory class of your
backend. PDNS will call this method after launching the backend.
</P
><P
> In the <CODE
CLASS="FUNCTION"
>declareArguments()</CODE
> method, the function <CODE
CLASS="FUNCTION"
>declare()</CODE
> is available. The exact definitions:
<P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>void declareArguments(const string &suffix="")</DT
><DD
><P
> This method is called to allow a backend to register configurable parameters. The suffix is the sub-name of this module. There is
no need to touch this suffix, just pass it on to the declare method.
</P
></DD
><DT
>void declare(const string &suffix, const string &param, const string &explanation, const string &value)</DT
><DD
><P
>The suffix is passed to your method, and can be passed on to declare. <B
CLASS="COMMAND"
>param</B
> is the name of your parameter.
<B
CLASS="COMMAND"
>explanation</B
> is what will appear in the output of --help. Furthermore, a default value can be supplied in the
<B
CLASS="COMMAND"
>value</B
> parameter.
</P
></DD
></DL
></DIV
>
</P
><P
> A sample implementation:
<PRE
CLASS="PROGRAMLISTING"
> void declareArguments(const string &suffix)
{
declare(suffix,"dbname","Pdns backend database name to connect to","powerdns");
declare(suffix,"user","Pdns backend user to connect as","powerdns");
declare(suffix,"host","Pdns backend host to connect to","");
declare(suffix,"password","Pdns backend password to connect with","");
}
</PRE
>
</P
><P
> After the arguments have been declared, they can be accessed from your backend using the <CODE
CLASS="FUNCTION"
>mustDo()</CODE
>,
<CODE
CLASS="FUNCTION"
>getArg()</CODE
> and <CODE
CLASS="FUNCTION"
>getArgAsNum()</CODE
> methods. The are defined as follows in the DNSBackend class:
</P
><P
> <P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>void setArgPrefix(const string &prefix)</DT
><DD
><P
> Must be called before any of the other accessing functions are used. Typical usage is '<CODE
CLASS="FUNCTION"
>setArgPrefix("mybackend"+suffix)</CODE
>'
in the constructor of a backend.
</P
></DD
><DT
>bool mustDo(const string &key)</DT
><DD
><P
> Returns true if the variable <CODE
CLASS="FUNCTION"
>key</CODE
> is set to anything but 'no'.
</P
></DD
><DT
>const string& getArg(const string &key)</DT
><DD
><P
> Returns the exact value of a parameter.
</P
></DD
><DT
>int getArgAsNum(const string &key)</DT
><DD
><P
> Returns the numerical value of a parameter. Uses <CODE
CLASS="FUNCTION"
>atoi()</CODE
> internally
</P
></DD
></DL
></DIV
>
</P
><P
> Sample usage from the BindBackend, using the <B
CLASS="COMMAND"
>bind-example-zones</B
> and <B
CLASS="COMMAND"
>bind-config</B
>
parameters.
<PRE
CLASS="PROGRAMLISTING"
> if(mustDo("example-zones")) {
insert(0,"www.example.com","A","1.2.3.4");
/* ... */
}
if(!getArg("config").empty()) {
BindParser BP;
BP.parse(getArg("config"));
}
</PRE
>
</P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="backend-error-reporting.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="rw-backends.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Reporting errors</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="backend-writers-guide.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Read/write slave-capable backends</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
