summaryrefslogtreecommitdiff
path: root/docs/Samba3-Developers-Guide
diff options
context:
space:
mode:
authorJelmer Vernooij <jelmer@samba.org>2005-06-13 10:23:53 +0000
committerGerald W. Carter <jerry@samba.org>2008-04-23 08:46:46 -0500
commit7639ec02141091657eb2eb0defc46b4b3cf09a73 (patch)
tree4d8cce2deff45d527668e49db78a71a8c0f92070 /docs/Samba3-Developers-Guide
parent8a5498d3bfa78923cbb4e6c79e152431223a4f86 (diff)
downloadsamba-7639ec02141091657eb2eb0defc46b4b3cf09a73.tar.gz
samba-7639ec02141091657eb2eb0defc46b4b3cf09a73.tar.bz2
samba-7639ec02141091657eb2eb0defc46b4b3cf09a73.zip
- Fix a couple of LaTeX escaping bugs.
- Fix urls in footnotes. - Cleanup developers docs. (This used to be commit d55b9f72ffbd0421cbde67915d9f275cc8956ed7)
Diffstat (limited to 'docs/Samba3-Developers-Guide')
-rw-r--r--docs/Samba3-Developers-Guide/NetBIOS.xml156
-rw-r--r--docs/Samba3-Developers-Guide/index.xml10
-rw-r--r--docs/Samba3-Developers-Guide/registry.dot10
-rw-r--r--docs/Samba3-Developers-Guide/registry.xml211
-rw-r--r--docs/Samba3-Developers-Guide/windows-debug.xml21
5 files changed, 5 insertions, 403 deletions
diff --git a/docs/Samba3-Developers-Guide/NetBIOS.xml b/docs/Samba3-Developers-Guide/NetBIOS.xml
deleted file mode 100644
index 04eaecd4ab..0000000000
--- a/docs/Samba3-Developers-Guide/NetBIOS.xml
+++ /dev/null
@@ -1,156 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
-<chapter id="netbios">
-<chapterinfo>
- <author>
- <firstname>Luke</firstname><surname>Leighton</surname>
- </author>
- <pubdate>12 June 1997</pubdate>
-</chapterinfo>
-
-<title>Definition of NetBIOS Protocol and Name Resolution Modes</title>
-
-<sect1>
-<title>NETBIOS</title>
-
-<para>
-NetBIOS runs over the following transports: TCP/IP; NetBEUI and IPX/SPX.
-Samba only uses NetBIOS over TCP/IP. For details on the TCP/IP NetBIOS
-Session Service NetBIOS Datagram Service, and NetBIOS Names, see
-rfc1001.txt and rfc1002.txt.
-</para>
-
-<para>
-NetBEUI is a raw NetBIOS frame protocol implementation that allows NetBIOS
-datagrams to be sent out over the 'wire' embedded within LLC frames.
-NetBEUI is not required when using NetBIOS over TCP/IP protocols and it
-is preferable NOT to install NetBEUI if it can be avoided.
-</para>
-
-<para>
-IPX/SPX is also not required when using NetBIOS over TCP/IP, and it is
-preferable NOT to install the IPX/SPX transport unless you are using Novell
-servers. At the very least, it is recommended that you do not install
-'NetBIOS over IPX/SPX'.
-</para>
-
-<para>
-[When installing Windows 95, you will find that NetBEUI and IPX/SPX are
-installed as the default protocols. This is because they are the simplest
-to manage: no Windows 95 user-configuration is required].
-</para>
-
-<para>
-NetBIOS applications (such as samba) offer their services (for example,
-SMB file and print sharing) on a NetBIOS name. They must claim this name
-on the network before doing so. The NetBIOS session service will then
-accept connections on the application's behalf (on the NetBIOS name
-claimed by the application). A NetBIOS session between the application
-and the client can then commence.
-</para>
-
-<para>
-NetBIOS names consist of 15 characters plus a 'type' character. This is
-similar, in concept, to an IP address and a TCP port number, respectively.
-A NetBIOS-aware application on a host will offer different services under
-different NetBIOS name types, just as a host will offer different TCP/IP
-services on different port numbers.
-</para>
-
-<para>
-NetBIOS names must be claimed on a network, and must be defended. The use
-of NetBIOS names is most suitable on a single subnet; a Local Area Network
-or a Wide Area Network.
-</para>
-
-<para>
-NetBIOS names are either UNIQUE or GROUP. Only one application can claim a
-UNIQUE NetBIOS name on a network.
-</para>
-
-<para>
-There are two kinds of NetBIOS Name resolution: Broadcast and Point-to-Point.
-</para>
-
-</sect1>
-
-<sect1>
-<title>BROADCAST NetBIOS</title>
-
-<para>
-Clients can claim names, and therefore offer services on successfully claimed
-names, on their broadcast-isolated subnet. One way to get NetBIOS services
-(such as browsing: see ftp.microsoft.com/drg/developr/CIFS/browdiff.txt; and
-SMB file/print sharing: see cifs4.txt) working on a LAN or WAN is to make
-your routers forward all broadcast packets from TCP/IP ports 137, 138 and 139.
-</para>
-
-<para>
-This, however, is not recommended. If you have a large LAN or WAN, you will
-find that some of your hosts spend 95 percent of their time dealing with
-broadcast traffic. [If you have IPX/SPX on your LAN or WAN, you will find
-that this is already happening: a packet analyzer will show, roughly
-every twelve minutes, great swathes of broadcast traffic!].
-</para>
-
-</sect1>
-
-<sect1>
-<title>NBNS NetBIOS</title>
-
-<para>
-rfc1001.txt describes, amongst other things, the implementation and use
-of, a 'NetBIOS Name Service'. NT/AS offers 'Windows Internet Name Service'
-which is fully rfc1001/2 compliant, but has had to take specific action
-with certain NetBIOS names in order to make it useful. (for example, it
-deals with the registration of &lt;1c&gt; &lt;1d&gt; &lt;1e&gt; names all in different ways.
-I recommend the reading of the Microsoft WINS Server Help files for full
-details).
-</para>
-
-<para>
-The use of a WINS server cuts down on broadcast network traffic for
-NetBIOS name resolution. It has the effect of pulling all the broadcast
-isolated subnets together into a single NetBIOS scope, across your LAN
-or WAN, while avoiding the use of TCP/IP broadcast packets.
-</para>
-
-<para>
-When you have a WINS server on your LAN, WINS clients will be able to
-contact the WINS server to resolve NetBIOS names. Note that only those
-WINS clients that have registered with the same WINS server will be
-visible. The WINS server _can_ have static NetBIOS entries added to its
-database (usually for security reasons you might want to consider putting
-your domain controllers or other important servers as static entries,
-but you should not rely on this as your sole means of security), but for
-the most part, NetBIOS names are registered dynamically.
-</para>
-
-<para>
-This provides some confusion for lots of people, and is worth mentioning
-here: a Browse Server is NOT a WINS Server, even if these services are
-implemented in the same application. A Browse Server _needs_ a WINS server
-because a Browse Server is a WINS client, which is _not_ the same thing].
-</para>
-
-<para>
-Clients can claim names, and therefore offer services on successfully claimed
-names, on their broadcast-isolated subnet. One way to get NetBIOS services
-(such as browsing: see ftp.microsoft.com/drg/developr/CIFS/browdiff.txt; and
-SMB file/print sharing: see cifs6.txt) working on a LAN or WAN is to make
-your routers forward all broadcast packets from TCP/IP ports 137, 138 and 139.
-You will find, however, if you do this on a large LAN or a WAN, that your
-network is completely swamped by NetBIOS and browsing packets, which is why
-WINS was developed to minimise the necessity of broadcast traffic.
-</para>
-
-<para>
-WINS Clients therefore claim names from the WINS server. If the WINS
-server allows them to register a name, the client's NetBIOS session service
-can then offer services on this name. Other WINS clients will then
-contact the WINS server to resolve a NetBIOS name.
-</para>
-
-</sect1>
-
-</chapter>
diff --git a/docs/Samba3-Developers-Guide/index.xml b/docs/Samba3-Developers-Guide/index.xml
index 492d5038ef..0e3eb10b3b 100644
--- a/docs/Samba3-Developers-Guide/index.xml
+++ b/docs/Samba3-Developers-Guide/index.xml
@@ -26,8 +26,6 @@ It's nothing more than a collection of documents written by samba developers abo
the internals of various parts of samba and the SMB protocol. It's still (and will always be) incomplete.
The most recent version of this document
can be found at <ulink url="http://devel.samba.org/">http://devel.samba.org/</ulink>.
-Please send updates to <ulink
-url="mailto:jelmer@samba.org">Jelmer Vernooij</ulink>.
</para>
<para>
@@ -37,6 +35,11 @@ distribution. A copy can be found on-line at <ulink
url="http://www.fsf.org/licenses/gpl.txt">http://www.fsf.org/licenses/gpl.txt</ulink>
</para>
+<warning>
+ <para>This document is incomplete and unmaintained. It is merely a
+ collection of development-related notes.</para>
+</warning>
+
</abstract>
</bookinfo>
@@ -54,7 +57,6 @@ url="http://www.fsf.org/licenses/gpl.txt">http://www.fsf.org/licenses/gpl.txt</u
<part>
<title>The protocol</title>
- <xi:include href="NetBIOS.xml"/>
<xi:include href="unix-smb.xml"/>
<xi:include href="cifsntdomain.xml"/>
@@ -76,7 +78,6 @@ url="http://www.fsf.org/licenses/gpl.txt">http://www.fsf.org/licenses/gpl.txt</u
<xi:include href="rpc_plugin.xml"/>
<xi:include href="vfs.xml"/>
- <xi:include href="registry.xml"/>
<xi:include href="parsing.xml"/>
<xi:include href="wins.xml"/>
<xi:include href="encryption.xml"/>
@@ -87,7 +88,6 @@ url="http://www.fsf.org/licenses/gpl.txt">http://www.fsf.org/licenses/gpl.txt</u
<title>Debugging and tracing</title>
<xi:include href="Tracing.xml"/>
- <xi:include href="windows-debug.xml"/>
<xi:include href="printing.xml"/>
</part>
diff --git a/docs/Samba3-Developers-Guide/registry.dot b/docs/Samba3-Developers-Guide/registry.dot
deleted file mode 100644
index b26f74b703..0000000000
--- a/docs/Samba3-Developers-Guide/registry.dot
+++ /dev/null
@@ -1,10 +0,0 @@
-digraph foo {
- libwinregistry -> libregistry;
- KConfig -> libregistry;
- gconf -> libregistry;
- "TDB (Samba)" -> libwinregistry;
- "Wine registry files" -> libwinregistry;
- "RPC (Remote windows server" -> libwinregistry;
- "NT4-style Registry files" -> libwinregistry;
- libregistry -> libwinregistry;
-}
diff --git a/docs/Samba3-Developers-Guide/registry.xml b/docs/Samba3-Developers-Guide/registry.xml
deleted file mode 100644
index bc394d71b7..0000000000
--- a/docs/Samba3-Developers-Guide/registry.xml
+++ /dev/null
@@ -1,211 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
-<chapter id="registry">
- <chapterinfo>
- &author.jelmer;
- <pubdate>24 September 2003</pubdate>
- </chapterinfo>
-
- <title>The registry subsystem</title>
-
- <sect1><title>Planned backends</title>
-
-<para>
- The new registry subsystem will work with several different backends:
-</para>
-
-<itemizedlist>
- <listitem><para>NT4 (NT4 registry files)</para></listitem>
- <listitem><para>TDB (Samba TDB files)</para></listitem>
- <listitem><para>RPC (Remote Registry over RPC, reg pipe)</para></listitem>
- <listitem><para>wine (Wine Registry Files)</para></listitem>
- <listitem><para>gconf (The GNOME configuration backend)</para></listitem>
-</itemizedlist>
-
-</sect1>
-
-<sect1><title>Data structures</title>
-
-<para>
-The following structure describes a registry key:
-</para>
-
-<programlisting>
-typedef struct reg_key_s {
- char *name; /* Name of the key */
- smb_ucs2_t *class_name; /* Name of key class */
- int type; /* One of REG_ROOT_KEY or REG_SUB_KEY */
- NTTIME last_mod; /* Time last modified */
- struct reg_key_s *owner;
- struct key_list_s *sub_keys; /* NULL indicates keys not available in memory, function should be called */
- struct val_list_s *values; /* NULL indicates values not available in memory, function should be called */
- SEC_DESC *security;
- REG_HANDLE *handle; /* Pointer to REG_HANDLE this key belongs to */
- void *backend_data; /* Pointer used by the backend */
-} REG_KEY;
-</programlisting>
-
-<para>The following structure describes a registry value:</para>
-
-<programlisting>
-typedef struct val_key_s {
- char *name; /* NULL if name not available */
- int data_type;
- int data_len;
- void *data_blk; /* Might want a separate block */
- REG_HANDLE *handle; /* Pointer to REG_HANDLE this key belongs to */
- void *backend_data;
-} REG_VAL;
-</programlisting>
-
-<para>The following structures are used for lists of subkeys or values:</para>
-
-<programlisting>
-/* container for registry subkey names */
-typedef struct key_list_s {
- TALLOC_CTX *ctx;
- uint32 num_subkeys;
- REG_KEY **subkeys;
-} REG_KEY_LIST;
-
-/* container for registry values */
-typedef struct val_list_s {
- TALLOC_CTX *ctx;
- uint32 num_vals;
- REG_VAL **vals;
-} REG_VAL_LIST;
-</programlisting>
-
-<para>
-And this structure is used for an instance of a registry (a registry file that's opened, a remote registry pipe we're connected to, etc).
-</para>
-
-<programlisting>
-typedef struct reg_handle_s {
- REGISTRY_OPS *functions;
- REG_KEY *root; /* NULL if not available */
- void *backend_data;
-} REG_HANDLE;
-</programlisting>
-
-</sect1>
-
-<sect1>
- <title>External interface</title>
-
-<programlisting>
-REG_HANDLE *reg_open(char *backend, char *location, BOOL try_full_load);
-REG_KEY *reg_open_key(REG_KEY *parent, char *name);
-REG_VAL *reg_key_get_val(REG_KEY *key, char *name);
-REG_VAL_LIST *reg_key_get_vals(REG_KEY *key);
-REG_KEY_LIST *reg_key_get_subkeys(REG_KEY *key);
-BOOL reg_key_del(REG_KEY *key);
-BOOL reg_val_del(REG_VAL *val);
-BOOL reg_key_add(REG_KEY *parent, REG_KEY *key);
-BOOL reg_val_add(REG_KEY *parent, REG_VAL *val):
-BOOL reg_val_update(REG_VAL *val);
-BOOL reg_key_update(REG_KEY *key);
-void reg_free_key(REG_KEY *key);
-void reg_free_val(REG_VAL *val);
-void reg_free(REG_HANDLE *h);
-void reg_free_key_list(REG_KEY_LIST *list):
-void reg_free_val_list(REG_VAL_LIST *list):
-</programlisting>
-
-</sect1>
-
-<sect1>
- <title>Utility functions</title>
-
- <para>The following helper functions are available:</para>
-
- <programlisting>
-void reg_key_list_init( REG_KEY_LIST *ctr );
-int reg_key_list_addkey( REG_KEY_LIST *ctr, const char *keyname );
-int reg_key_list_numkeys( REG_KEY_LIST *ctr );
-char* reg_key_list_specific_key( REG_KEY_LIST *ctr, uint32 key_index );
-void reg_key_list_destroy( REG_KEY_LIST *ctr );
-void reg_val_list_init( REG_VAL_LIST *ctr );
-int reg_val_list_numvals( REG_VAL_LIST *ctr );
-void free_registry_value( REG_VAL *val );
-uint8* regval_data_p( REG_VAL *val );
-int regval_size( REG_VAL *val );
-char* regval_name( REG_VAL *val );
-uint32 regval_type( REG_VAL *val );
-TALLOC_CTX* reg_val_list_getctx( REG_VAL_LIST *val );
-int reg_val_list_addvalue( REG_VAL_LIST *ctr, const char *name, uint16 type,
- const char *data_p, size_t size );
-int reg_val_list_copyvalue( REG_VAL_LIST *ctr, REG_VAL *val );
-int reg_val_list_delvalue( REG_VAL_LIST *ctr, const char *name );
-void reg_val_list_destroy( REG_VAL_LIST *ctr );
-</programlisting>
-
-</sect1>
-
-<sect1>
- <title>Writing backends</title>
-
-<para>There are basically two ways of reading data from the registry: loading
-it all into memory and then working in this copy in memory, or
-re-reading/re-opening it every time necessary.</para>
-
-<para>This interface aims to support both types. </para>
-
-<para>A registry backend should provide the following functions:</para>
-
-<programlisting>
-typedef struct {
- REG_HANDLE *(*open_registry) (const char *location, BOOL try_complete_load);
- REG_KEY *(*open_root_key) (REG_HANDLE *);
- REG_KEY *(*open_key_rel) (REG_KEY *parent, const char *name);
- /* if open_key_abs is set to NULL, a default implementation will be provided. */
- REG_KEY *(*open_key_abs) (REG_HANDLE *, const char *name);
- REG_KEY_LIST *(*get_subkeys) (REG_KEY *);
- REG_VAL_LIST *(*get_values) (REG_KEY *);
- BOOL (*add_key)(REG_KEY *, REG_KEY *);
- BOOL (*update_key)(REG_KEY *);
- BOOL (*del_key)(REG_KEY *);
- BOOL (*add_value)(REG_KEY *, REG_VAL *);
- BOOL (*update_value)(REG_VAL *);
- BOOL (*del_value)(REG_VAL *);
- REG_VAL *(*get_value) (REG_KEY *, const char *name);
- /* It is not guaranteed that no data has been stored before save()
- * has been called. This function is only useful for backends that
- * store the data in memory and then write out the whole registry at once */
- BOOL (*save)(REG_HANDLE *, const char *location);
- BOOL (*close_registry) (REG_HANDLE *);
- void (*free_key)(REG_KEY *);
- void (*free_value)(REG_VAL *);
-} REGISTRY_OPS;
-</programlisting>
-
-<para>open_root_key() is optional. It's only called if the
- <parameter>root</parameter> field of the REG_HANDLE struct is NULL.</para>
-
-<para>open_key_abs() is optional. If it's NULL, the frontend will
- provide a replacement, using open_key_rel().</para>
-
-<para>get_values() and get_value() are optional. They're only called if
-the <parameter>values</parameter> field of the REG_KEY struct is NULL.</para>
-
-<para>get_subkeys() and get_key() are optional. THey're only called
- if the <parameter>subkeys</parameter> field of the REG_KEY struct is NULL.</para>
-
-</sect1>
-
-<sect1><title>Memory allocation</title>
-
-<para>Okay, so who's responsible for what parts of the memory? </para>
-
-<para>The memory is basically maintained by the backends. When the user
-is finished using a particular structure, it should call the related free
-function for the structure it's freeing.</para>
-
-<para>The backend should then decide what to do with the structure. It may
-choose to free it, or, if it's maintaining single copies of everything in
-memory, may choose to ignore the free and free it when the registry is closed.
-</para>
-
-</sect1>
-
-</chapter>
diff --git a/docs/Samba3-Developers-Guide/windows-debug.xml b/docs/Samba3-Developers-Guide/windows-debug.xml
deleted file mode 100644
index db0560c6e1..0000000000
--- a/docs/Samba3-Developers-Guide/windows-debug.xml
+++ /dev/null
@@ -1,21 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
-<chapter id="windows-debug">
- <chapterinfo>
- &author.jelmer;
- &author.tridge;
- </chapterinfo>
-
- <title>Finding useful information on windows</title>
-
- <sect1><title>Netlogon debugging output</title>
-
- <procedure>
- <step><para>stop netlogon service on PDC</para></step>
- <step><para>rename original netlogon.dll to netlogon.dll.original</para></step>
- <step><para>copy checked version of netlogon.dll to system32 directory</para></step>
- <step><para>set HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Netlogon\Parameters\DBFlag to 0x20000004</para></step>
- <step><para>start netlogon service on PDC</para></step>
- </procedure>
-</sect1>
-</chapter>