Definition of NetBIOS Protocol and Name Resolution Modes

Samba Architecture

The samba DEBUG system

  >debugfile< :== { >debugmsg< }

  >debugmsg<  :== >debughdr< '\n' >debugtext<

  >debughdr<  :== '[' TIME ',' LEVEL ']' FILE ':' [FUNCTION] '(' LINE ')'

  >debugtext< :== { >debugline< }

  >debugline< :== TEXT '\n'

    [1998/08/03 12:55:25, 1] nmbd.c:(659)
      Netbios nameserver version 1.9.19-prealpha started.
      Copyright Andrew Tridgell 1994-1997
    [1998/08/03 12:55:25, 3] loadparm.c:(763)
      Initializing global parameters

printf( "This is a %s message.\n", "debug" );

DEBUG( 0, ( "This is a %s message.\n", "debug" ) );

    [1998/07/30 16:00:51, 0] file.c:function(128)
      This is a debug message.

    DEBUG( 0, ("The test returned " ) );
    if( test() )
      DEBUG(0, ("True") );
    else
      DEBUG(0, ("False") );
    DEBUG(0, (".\n") );

    [1998/07/30 16:00:51, 0] file.c:function(256)
      The test returned
    [1998/07/30 16:00:51, 0] file.c:function(258)
      True
    [1998/07/30 16:00:51, 0] file.c:function(261)
      .

    DEBUG( 0, ("This is the first line.\n" ) );
    DEBUGADD( 0, ("This is the second line.\nThis is the third line.\n" ) );

    [1998/07/30 16:00:51, 0] file.c:function(512)
      This is the first line.
      This is the second line.
      This is the third line.

  DEBUG(3,("send_local_master_announcement: type %x for name %s on subnet %s for workgroup %s\n",
            type, global_myname, subrec->subnet_name, work->work_group));

  DEBUG( 3, ( "send_local_master_announcement: " ) );
  DEBUGADD( 3, ( "type %x for name %s ", type, global_myname ) );
  DEBUGADD( 3, ( "on subnet %s ", subrec->subnet_name ) );
  DEBUGADD( 3, ( "for workgroup %s\n", work->work_group ) );

  if( DEBUGLVL( 3 ) )
    {
    dbgtext( "send_local_master_announcement: " );
    dbgtext( "type %x for name %s ", type, global_myname );
    dbgtext( "on subnet %s ", subrec->subnet_name );
    dbgtext( "for workgroup %s\n", work->work_group );
    }

Coding Suggestions

So you want to add code to Samba ...

One of the daunting tasks facing a programmer attempting to write code for Samba is understanding the various coding conventions used by those most active in the project. These conventions were mostly unwritten and helped improve either the portability, stability or consistency of the code. This document will attempt to document a few of the more important coding practices used at this time on the Samba project. The coding practices are expected to change slightly over time, and even to grow as more is learned about obscure portability considerations. Two existing documents samba/source/internals.doc and samba/source/architecture.doc provide additional information.

The loosely related question of coding style is very personal and this document does not attempt to address that subject, except to say that I have observed that eight character tabs seem to be preferred in Samba source. If you are interested in the topic of coding style, two oft-quoted documents are:

http://lxr.linux.no/source/Documentation/CodingStyle

http://www.fsf.org/prep/standards_toc.html

But note that coding style in Samba varies due to the many different programmers who have contributed.

Following are some considerations you should use when adding new code to Samba. First and foremost remember that:

Portability is a primary consideration in adding function, as is network compatability with de facto, existing, real world CIFS/SMB implementations. There are lots of platforms that Samba builds on so use caution when adding a call to a library function that is not invoked in existing Samba code. Also note that there are many quite different SMB/CIFS clients that Samba tries to support, not all of which follow the SNIA CIFS Technical Reference (or the earlier Microsoft reference documents or the X/Open book on the SMB Standard) perfectly.

Here are some other suggestions:

1. use d_printf instead of printf for display text reason: enable auto-substitution of translated language text

2. use SAFE_FREE instead of free reason: reduce traps due to null pointers

3. don't use bzero use memset, or ZERO_STRUCT and ZERO_STRUCTP macros reason: not POSIX

4. don't use strcpy and strlen (use safe_* equivalents) reason: to avoid traps due to buffer overruns

5. don't use getopt_long, use popt functions instead reason: portability

6. explicitly add const qualifiers on parm passing in functions where parm is input only (somewhat controversial but const can be #defined away)

7. when passing a va_list as an arg, or assigning one to another please use the VA_COPY() macro reason: on some platforms, va_list is a struct that must be initialized in each function...can SEGV if you don't.

8. discourage use of threads reason: portability (also see architecture.doc)

9. don't explicitly include new header files in C files - new h files should be included by adding them once to includes.h reason: consistency

10. don't explicitly extern functions (they are autogenerated by "make proto" into proto.h) reason: consistency

11. use endian safe macros when unpacking SMBs (see byteorder.h and internals.doc) reason: not everyone uses Intel

12. Note Unicode implications of charset handling (see internals.doc). See pull_* and push_* and convert_string functions. reason: Internationalization

13. Don't assume English only reason: See above

14. Try to avoid using in/out parameters (functions that return data which overwrites input parameters) reason: Can cause stability problems

15. Ensure copyright notices are correct, don't append Tridge's name to code that he didn't write. If you did not write the code, make sure that it can coexist with the rest of the Samba GPLed code.

16. Consider usage of DATA_BLOBs for length specified byte-data. reason: stability

17. Take advantage of tdbs for database like function reason: consistency

18. Don't access the SAM_ACCOUNT structure directly, they should be accessed via pdb_get...() and pdb_set...() functions. reason: stability, consistency

19. Don't check a password directly against the passdb, always use the check_password() interface. reason: long term pluggability

20. Try to use asprintf rather than pstrings and fstrings where possible

21. Use normal C comments / * instead of C++ comments // like this. Although the C++ comment format is part of the C99 standard, some older vendor C compilers do not accept it.

22. Try to write documentation for API functions and structures explaining the point of the code, the way it should be used, and any special conditions or results. Mark these with a double-star comment start / ** so that they can be picked up by Doxygen, as in this file.

23. Keep the scope narrow. This means making functions/variables static whenever possible. We don't want our namespace polluted. Each module should have a minimal number of externally visible functions or variables.

24. Use function pointers to keep knowledge about particular pieces of code isolated in one place. We don't want a particular piece of functionality to be spread out across lots of places - that makes for fragile, hand to maintain code. Instead, design an interface and use tables containing function pointers to implement specific functionality. This is particularly important for command interpreters.

25. Think carefully about what it will be like for someone else to add to and maintain your code. If it would be hard for someone else to maintain then do it another way.

The suggestions above are simply that, suggestions, but the information may help in reducing the routine rework done on new code. The preceeding list is expected to change routinely as new support routines and macros are added.

Samba Internals

call_api(int prcnt, int drcnt, int mprcnt, int mdrcnt, 
	char *param, char *data, char **rparam, char **rdata);

The smb.conf file

	param name = parameter value string \
	with line continuation.

    param name = parameter value string     with line continuation.

	param name = parameter value string \
    \
    with line continuation.

param name = parameter value string         with line continuation.

	param name = parameter value string \
	; comment \
    with a comment.

param name = parameter value string     ; comment     with a comment.

	[ section   name ] garbage \
    param  name  = value

	[section name]
    param name = value

  <file>            :==  { <section> } EOF
  <section>         :==  <section header> { <parameter line> }
  <section header>  :==  '[' NAME ']'
  <parameter line>  :==  NAME '=' VALUE NL

NetBIOS in a Unix World

Tracing samba system calls

This file describes how to do a system call trace on Samba to work out what its doing wrong. This is not for the faint of heart, but if you are reading this then you are probably desperate.

Actually its not as bad as the the above makes it sound, just don't expect the output to be very pretty :-)

Ok, down to business. One of the big advantages of unix systems is that they nearly all come with a system trace utility that allows you to monitor all system calls that a program is making. This is extremely using for debugging and also helps when trying to work out why something is slower than you expect. You can use system tracing without any special compilation options.

The system trace utility is called different things on different systems. On Linux systems its called strace. Under SunOS 4 its called trace. Under SVR4 style systems (including solaris) its called truss. Under many BSD systems its called ktrace.

The first thing you should do is read the man page for your native system call tracer. In the discussion below I'll assume its called strace as strace is the only portable system tracer (its available for free for many unix types) and its also got some of the nicest features.

Next, try using strace on some simple commands. For example, strace ls or strace echo hello.

You'll notice that it produces a LOT of output. It is showing you the arguments to every system call that the program makes and the result. Very little happens in a program without a system call so you get lots of output. You'll also find that it produces a lot of "preamble" stuff showing the loading of shared libraries etc. Ignore this (unless its going wrong!)

For example, the only line that really matters in the strace echo hello output is:

write(1, "hello\n", 6)                  = 6

all the rest is just setting up to run the program.

Ok, now you're familiar with strace. To use it on Samba you need to strace the running smbd daemon. The way I tend ot use it is to first login from my Windows PC to the Samba server, then use smbstatus to find which process ID that client is attached to, then as root I do strace -p PID to attach to that process. I normally redirect the stderr output from this command to a file for later perusal. For example, if I'm using a csh style shell:

strace -f -p 3872 >& strace.out

or with a sh style shell:

strace -f -p 3872 > strace.out 2>&1

Note the "-f" option. This is only available on some systems, and allows you to trace not just the current process, but any children it forks. This is great for finding printing problems caused by the "print command" being wrong.

Once you are attached you then can do whatever it is on the client that is causing problems and you will capture all the system calls that smbd makes.

So how do you interpret the results? Generally I search through the output for strings that I know will appear when the problem happens. For example, if I am having touble with permissions on a file I would search for that files name in the strace output and look at the surrounding lines. Another trick is to match up file descriptor numbers and "follow" what happens to an open file until it is closed.

Beyond this you will have to use your initiative. To give you an idea of what you are looking for here is a piece of strace output that shows that /dev/null is not world writeable, which causes printing to fail with Samba:

[pid 28268] open("/dev/null", O_RDWR)   = -1 EACCES (Permission denied)
[pid 28268] open("/dev/null", O_WRONLY) = -1 EACCES (Permission denied)

The process is trying to first open /dev/null read-write then read-only. Both fail. This means /dev/null has incorrect permissions.

NT Domain RPC's

        switch (switch_value)
        case 1:
        {
            ID_INFO_1     id_info_1;
        }

        initial SMBopenX request:         RPC API command 0x26 params:
        "\\PIPE\\lsarpc"                  0x65 0x63; 0x72 0x70; 0x44 0x65;
        "\\PIPE\\srvsvc"                  0x73 0x76; 0x4E 0x00; 0x5C 0x43;

abstract (0x4B324FC8, 0x01D31670, 0x475A7812, 0x88E16EBF, 0x00000003)
transfer (0x8A885D04, 0x11C91CEB, 0x0008E89F, 0x6048102B, 0x00000002)

switch (info class)
case 3:
case 5:
{
DOM_INFO domain info, levels 3 and 5 (are the same).
}

return    0 - indicates success

if (valid_user)
{
	UINT16      3 - switch value indicating USER_INFO structure.
    VOID*     non-zero - pointer to USER_INFO structure
    USER_INFO user logon information

    UINT32    1 - Authoritative response; 0 - Non-Auth?

    return    0 - indicates success
}
else
{
	UINT16    0 - switch value.  value to indicate no user presumed.
    VOID*     0x0000 0000 - indicates no USER_INFO structure.

    UINT32    1 - Authoritative response; 0 - Non-Auth?

    return    0xC000 0064 - NT_STATUS_NO_SUCH_USER.
}