Skip to content

Commit

Permalink
Man pages for ntdb tools missing
Browse files Browse the repository at this point in the history 
Copied and modified from tdb man pages.  Avoided reproducing API documentation
which is extensively documented in the ntdb.h header already.

BUG: https://bugzilla.samba.org/show_bug.cgi?id=10000

Signed-off-by: Rusty Russell <[email protected]>
Reviewed-by: Jeremy Allison <[email protected]>
  • Loading branch information
@rustyrussell @jrasamba
rustyrussell authored and jrasamba committed Aug 19, 2013
1 parent 4f96d57 commit 3e11421
Show file tree
Hide file tree
Showing 6 changed files with 708 additions and 5 deletions.
132 changes: 132 additions & 0 deletions lib/ntdb/man/ntdb.3.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<refentry>
<refmeta>
<refentrytitle>ntdb</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Samba</refmiscinfo>
<refmiscinfo class="manual">System Administration tools</refmiscinfo>
<refmiscinfo class="version">4.0</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ntdb</refname>
<refpurpose>A not-so trivial keyword/data database system</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>#include &lt;ntdb.h&gt;</synopsis>
</refsynopsisdiv>
<refsect1><title>DESCRIPTION</title>
<para>
If you have previously used the tdb library from Samba, much of
this will seem familiar, but there are some API changes which a
compiler will warn you about if you simply replace 'tdb' with
'ntdb' in your code! The on-disk format for ntdb is
incompatible with tdb.
</para>
<para>
tdb's API was based on gdbm, and ntdb continues this tradition,
with enhancements. A differences guide is available in the text
file <filename>lib/ntdb/doc/TDB_porting.txt</filename> in the
SAMBA source tree.
</para>
</refsect1>
<refsect1><title>NTDB API OVERVIEW</title>
<para>
The complete API is documented in the ntdb.h header, which is
kept up-to-date and recommended reading.
</para>
<para>
Normal usage is to call ntdb_open() to create or open an ntdb
file. ntdb_store() is used to add records, ntdb_fetch() is used
to fetch them. Traversals are supported via callback
(ntdb_traverse()) or iteration (ntdb_firstkey() and
ntdb_nextkey()). Transactions are supported for batching
updates or reads atomically, using ntdb_transaction_start() and
ntdb_transaction_commit().
</para>
<refsect2><title>Use With Talloc</title>
<para>
ntdb_open() takes an optional linked list of attributes:
in particular you can specify an alternate allocator (such as
talloc):
</para>
<programlisting>
#include &lt;talloc.h&gt;
#include &lt;ntdb.h&gt;

static void *my_alloc(const void *owner, size_t len, void *priv)
{
return talloc_size(owner, len);
}

static void *my_expand(void *old, size_t newlen, void *priv)
{
return talloc_realloc_size(NULL, old, newlen);
}

static void my_free(void *old, void *priv)
{
talloc_free(old);
}

/* This opens an ntdb file as a talloc object with given parent. */
struct ntdb_context *ntdb_open_talloc(const void *parent,
const char *filename)
{
struct ntdb_context *ntdb;
union ntdb_attribute alloc;

alloc.base.attr = NTDB_ATTRIBUTE_ALLOCATOR;
alloc.base.next = NULL;
alloc.alloc.alloc = my_alloc;
alloc.alloc.expand = my_expand;
alloc.alloc.free = my_free;

ntdb = ntdb_open(filename, NTDB_DEFAULT, O_RDWR|O_CREAT, 0600,
&amp;alloc);
if (ntdb) {
talloc_steal(parent, ntdb);
talloc_set_name(ntdb, "%s", filename);
}
return ntdb;
}
</programlisting>
</refsect2>
</refsect1>
<refsect1><title>SEE ALSO</title>
<para>
<ulink url="http://tdb.samba.org/"/>
</para>
</refsect1>

<refsect1><title>AUTHOR</title>
<para> The original tdb software was created by Andrew Tridgell, and
is now developed by the
Samba Team as an Open Source project similar to the way the
Linux kernel is developed. ntdb was derived from tdb, but mostly
rewritten by Rusty Russell.
</para>
</refsect1>

<refsect1><title>COPYRIGHT/LICENSE</title>
<para>
Copyright (C) Rusty Russell 2013, IBM Corporation
</para>
<para>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as
published by the Free Software Foundation; either version 3 of the
License, or (at your option) any later version.
</para>
<para>
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
</para>
<para>
You should have received a copy of the GNU General Public License
along with this program; if not, see http://www.gnu.org/licenses/.
</para>
</refsect1>
</refentry>
150 changes: 150 additions & 0 deletions lib/ntdb/man/ntdbbackup.8.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,150 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<refentry id="ntdbbackup.8">

<refmeta>
<refentrytitle>ntdbbackup</refentrytitle>
<manvolnum>8</manvolnum>
<refmiscinfo class="source">Samba</refmiscinfo>
<refmiscinfo class="manual">System Administration tools</refmiscinfo>
<refmiscinfo class="version">4.0</refmiscinfo>
</refmeta>


<refnamediv>
<refname>ntdbbackup</refname>
<refpurpose>tool for backing up and for validating the integrity of samba .ntdb files</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis>
<command>ntdbbackup</command>
<arg choice="opt">-s suffix</arg>
<arg choice="opt">-v</arg>
<arg choice="opt">-h</arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsect1>
<title>DESCRIPTION</title>

<para>This tool is part of the <citerefentry><refentrytitle>samba</refentrytitle>
<manvolnum>1</manvolnum></citerefentry> suite.</para>

<para><command>ntdbbackup</command> is a tool that may be used to backup samba .ntdb
files. This tool may also be used to verify the integrity of the .ntdb files prior
to samba startup or during normal operation. If it finds file damage and it finds
a prior backup the backup file will be restored.
</para>
</refsect1>


<refsect1>
<title>OPTIONS</title>

<variablelist>

<varlistentry>
<term>-h</term>
<listitem><para>
Get help information.
</para></listitem>
</varlistentry>

<varlistentry>
<term>-s suffix</term>
<listitem><para>
The <command>-s</command> option allows the administrator to specify a file
backup extension. This way it is possible to keep a history of ntdb backup
files by using a new suffix for each backup.
</para> </listitem>
</varlistentry>

<varlistentry>
<term>-v</term>
<listitem><para>
The <command>-v</command> will check the database for damages (corrupt data)
which if detected causes the backup to be restored.
</para></listitem>
</varlistentry>

</variablelist>
</refsect1>


<refsect1>
<title>COMMANDS</title>

<para><emphasis>GENERAL INFORMATION</emphasis></para>

<para>
The <command>ntdbbackup</command> utility can safely be run at any time. It was designed so
that it can be used at any time to validate the integrity of ntdb files, even during Samba
operation. Typical usage for the command will be:
</para>

<para>ntdbbackup [-s suffix] *.ntdb</para>

<para>
Before restarting samba the following command may be run to validate .ntdb files:
</para>

<para>ntdbbackup -v [-s suffix] *.ntdb</para>

<para>
Note that Samba 4 can use .tdb files instead, so you should
use <command>tdbbackup</command> on those files.
</para>

<para>
Samba .tdb and .ntdb files are stored in various locations, be sure to run backup all
.(n)tdb files on the system. Important files includes:
</para>

<itemizedlist>
<listitem><para>
<command>secrets.(n)tdb</command> - usual location is in the /usr/local/samba/private
directory, or on some systems in /etc/samba.
</para></listitem>

<listitem><para>
<command>passdb.(n)tdb</command> - usual location is in the /usr/local/samba/private
directory, or on some systems in /etc/samba.
</para></listitem>

<listitem><para>
<command>*.tdb</command> and <command>*.ntdb</command> located in the /usr/local/samba/var directory or on some
systems in the /var/cache or /var/lib/samba directories.
</para></listitem>
</itemizedlist>

</refsect1>

<refsect1>
<title>VERSION</title>

<para>This man page is correct for version 4 of the Samba suite.</para>
</refsect1>

<refsect1>
<title>SEE ALSO</title>

<para>
tdbbackup(8), ntdbrestore(8)
</para>
</refsect1>

<refsect1>
<title>AUTHOR</title>

<para>
The original Samba software and related utilities were created by Andrew Tridgell.
Samba is now developed by the Samba Team as an Open Source project similar to the way
the Linux kernel is developed.
</para>

<para>The ntdbbackup man page was written by Rusty Russell,
based on the tdbbackup man page by John H Terpstra.</para>
</refsect1>

</refentry>
93 changes: 93 additions & 0 deletions lib/ntdb/man/ntdbdump.8.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<refentry id="ntdbdump.8">

<refmeta>
<refentrytitle>ntdbdump</refentrytitle>
<manvolnum>8</manvolnum>
<refmiscinfo class="source">Samba</refmiscinfo>
<refmiscinfo class="manual">System Administration tools</refmiscinfo>
<refmiscinfo class="version">4.0</refmiscinfo>
</refmeta>


<refnamediv>
<refname>ntdbdump</refname>
<refpurpose>tool for printing the contents of an NTDB file</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis>
<command>ntdbdump</command>
<arg choice="opt">-k <replaceable>keyname</replaceable></arg>
<arg choice="opt">-e</arg>
<arg choice="opt">-h</arg>
<arg choice="req">filename</arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsect1>
<title>DESCRIPTION</title>

<para>This tool is part of the <citerefentry><refentrytitle>samba</refentrytitle>
<manvolnum>1</manvolnum></citerefentry> suite.</para>

<para><command>ntdbdump</command> is a very simple utility that 'dumps' the
contents of a NTDB (New Trivial DataBase) file to standard output in a
human-readable format.
</para>

<para>This tool can be used when debugging problems with NTDB files. It is
intended for those who are somewhat familiar with Samba internals.
</para>
</refsect1>

<refsect1>
<title>OPTIONS</title>

<variablelist>

<varlistentry>
<term>-h</term>
<listitem><para>
Get help information.
</para></listitem>
</varlistentry>

<varlistentry>
<term>-k <replaceable>keyname</replaceable></term>
<listitem><para>
The <command>-k</command> option restricts dumping to a single key, if found.
</para> </listitem>
</varlistentry>

</variablelist>
</refsect1>

<refsect1>
<title>SEE ALSO</title>

<para>
tdbdump(8), ntdbtool(8)
</para>
</refsect1>

<refsect1>
<title>VERSION</title>

<para>This man page is correct for version 4 of the Samba suite.</para>
</refsect1>

<refsect1>
<title>AUTHOR</title>

<para>
The original Samba software and related utilities were created by Andrew Tridgell.
Samba is now developed by the Samba Team as an Open Source project similar to the way
the Linux kernel is developed.
</para>

<para>The ntdbdump man page was written by Rusty Russell, base on the tdbdump man page by Jelmer Vernooij.</para>
</refsect1>

</refentry>
Loading

0 comments on commit 3e11421

Please sign in to comment.