This page describes a Samba setup suited only for simple home network use. How much of it can be applied to other configurations than mine I cannot guess, since I have basically no knowledge about Windows networking.

It might be helpful to keep in mind what my use of Samba does not include:

  • I don't want to emulate a proper Windows network
  • I don't want to have a Windows domain (whatever that is, exactly)
  • I don't want to use anything else than phpLDAPadmin, or some other general purpose LDAP tool, to perform administration tasks, specifically
    • add or remove users and groups
    • change passwords (ok, I allow smbpasswd :-)

Debian packages

The following Debian packages need to be installed


(smbclient is necessary only for test purposes)


Configuration file reference 
man smb.conf
Password encryption 
Samba & LDAP (precise, short & helpful!)
Samba & LDAP (also quite detailed)
Samba & LDAP (Samba3-HOWTO, local link to ldapsam docs)
Samba & LDAP (local docs) 
Information about LM Password Hash and NT Password Hash


Primary Domain Controller
Backup Domain Controller
Trivial Databaes. Samba uses this format to store information in several files such as secrets.tdb and passdb.tdb (both located in /var/lib/samba on my machine)

samba configuration


  • workgroup = ARBEITSGRUPPE (the same workgroup as on Francesca's PC)
  • encrypted passwords = yes
  • use WINS settings from DHCP = no
  • start samba as daemon (not from inetd) = yes
  • create password file with encrypted passwords = yes

The last option creates the file


Every samba user now needs an entry in this file. Such an entry can be created with


Notes about passwords:

  • the question "create password file with encrypted passwords" reflects the setting "encrypt passwords" in smb.conf
  • if this is set to yes, then samba cannot use PAM authentication; this restriction is documented in man smb.conf under the option "obey pam restrictions"
  • since I have never run samba with "enrypt passwords = no", I cannot really say how PAM would be enabled; possibly this would work by default because the Debian package is compiled with PAM support, but I am not sure of this
  • if PAM were used, samba would by default only use pure authentication; setting "obey pam restrictions = yes" would tell samba to also use PAM's account and session management

Note: Further down there is a section that explains how to use LDAP as the user database.


swat is no longer supported upstream, and Debian no longer distributes the tool. This section should be converted to show the manual configuration of /etc/samba/smb.conf.


On the "password" tab, create the users

  • patrick
  • francesca

Use the same passwords as the system users to prevent confusion.

Because I don't want anonymous access, authentication will be required later on to access the shares we are going to create. The users we just created will be used for authentication.

Note: Further down there is a section that explains how to use LDAP as the user database.


On the command line, create a directory for each share that we are going to create:

mkdir -p /var/samba/daten
chown patrick:patrick /var/samba/daten
chmod 700 /var/samba/daten

In swat, on the "shares" tab create and configure a share

  • path = /var/samba/daten
  • force user = patrick (after a client has authenticated, samba will go on to use user "patrick", including its primary group)
  • read only = false
  • hide files = lost+found
  • available = yes
  • create mask = 0700
  • directory mask = 0700

The latter 2 options are available only in the "Advanced" view. Together with the "force user" setting, the mask options are useful to prevent SSH and SFTP sessions to snoop around inside the data served by samba.

Change the "homes" share:

  • browseable = yes

IMPORTANT: Do not use share names that are longer than 12 characters, or that contain spaces. These shares are not visible in the Mac OS X Finder when clicking on the Samba server to list its shares. Other clients such as Windows 95 will have this problem, too. The problem can be traced to a very old limitation in the Windows networking world, which is probably even rooted in the infamous 8.3 filename limitation. See this Microsoft KB article for some illuminating details. Samba intentionally implements the 12-characters-no-spaces limitation because it wants to be a faithful reproduction of how Windows networking works. Unfortunately, the Mac OS X Finder chooses a historical approach to browse SMB shares, which exposes the 12 character limitation (see this entry on one of Apple's mailing lists). The limitation can be circumvented by using the Finder's "Connect to server" dialog (located in the "Go to" menu) and entering the share name like this: "smb://pelargir/abc123abc123abc123".


On the "Globals" tab, make the following changes:

  • Under "Protocol Options", set the option "unix extensions" = No
    • The reason why we need to disable this is the Mac OS X Finder (not the command line!), which tries to chmod files/directories through the extensions if they are on. This does not work because the share definitions use forced permissions. It is currently unclear what limitations this imposes on well-behaved clients (e.g. Linux, the Mac OS X command line).


List all shares:

smbclient -L //pelargir -U%

Connect to a user's home share:

smbclient //pelargir/francesca -Ufrancesca%<pwd>

(on the smbclient command line, it is now possible to say "dir" to list all files)


Task overview

To integrate Samba with LDAP, the following tasks need to be done in the listed order. Most of them are explained in more detail in one of the following chapters.

  • configure the LDAP server
    • use the schema defined by Samba
    • use additional indices
    • add new ACLs for the Samba DN (the DN that Samba is going to use for directory access)
  • modify the LDAP directory
    • add Samba DN to the directory
    • add ou=samba subtree to directory
    • augment existing group and user entries in the directory with samba object classes and attributes
  • configure Samba to use LDAP
  • activate the new configuration in these 3 steps
    • temporarily configure the LDAP server so that the samba DN has write access to the directory base
    • restart Samba (will create a sambaDomain entry in the directory base)
    • configure the LDAP server back to the original ACLs
  • use smbpasswd to set user passwords
  • cleanup
    • move sambaDomain entry to ou=samba subtree
    • remove old password file

Configure the LDAP server


Manually copy samba.schema into the LDAP schema directory. The file is provided by Debian package samba-doc.

cp /usr/share/doc/samba-doc/examples/LDAP/samba.schema.gz /etc/ldap/schema
cd /etc/ldap/schema
gunzip samba.schema.gz

Configure slapd to load the schema by adding the following line to /etc/ldap/slapd.conf:

include         /etc/ldap/schema/samba.schema

Note: There is an open issue in the Debian bugtracker that requests that samba.schema be dropped into its proper place by one of the Samba packages. See


Configure additional indices by adding the following lines to /etc/ldap/slapd.conf:

# Indices for Samba (taken from Samba3-HOWTO)
index sambaSID eq,sub
index sambaPrimaryGroupSID eq
index sambaDomainName eq
index default sub
## required to support pdb_getsampwnam
index uid pres,sub,eq
## required to support pdb_getsambapwrid()
index displayName pres,sub,eq

After modifying the file, perform reindexing:

/etc/init.d/slapd stop
slapindex -n 1
/etc/init.d/slapd start
chown openldap:openldap /var/lib/ldap/*

Note: I am not sure if any of these indices are required for Samba/LDAP integration to work. I was too lazy to test this out...


Note: The actual ACLs developed in theory in this chapter can be found over on the OpenLDAP page.

Samba is not interested in the userPassword attribute, it uses the special attributes sambaLMPassword and sambaNTPassword for storing hashes of the user's password. This requires that these two new password hashes are protected from general access.

To develop an ACL for the Samba password attributes, let's first examine the ACL for userPassword:

access to attrs=userPassword,shadowLastChange
  by anonymous auth
  by self write
  by dn.exact="cn=libnss-ldap-root,ou=users,dc=herzbube,dc=ch" read
  by * none

Now let's dicuss why any one of the rules in the above ACL should apply to Samba password attributes:

  • anonymous does not need access (for authentication) because binding happens with userPassword
  • self does not need access because Samba always binds with its own DN, never with the user's DN
  • although strictly speaking self does not need any access at all, we should give self read access - I think it's sensible that an entry should see at least all of its own attributes
  • libnss-ldap-root indicates through its name that it is reserved for usage by libnss-ldap; since this service has no need to see Samba password hashes, it also does not need access

This leaves us with no access to Samba password attributes at all. Since this clearly cannot be the solution, we have the following possibilities to resolve the problem:

  • give Samba access through the directory's admin (or root) DN
    • this solution is not viable since the admin DN has read and write access to everything, which is obviously not the proper access level for Samba
  • give Samba access through the libnss-ldap-root DN
    • this solution is undesirable since it would compromise the clear purpose of libnss-ldap-root (namely that it should be used by libnss-ldap when it runs as root)
  • rename libnss-ldap-root to something like readonly-password and give Samba access through that DN
    • the advantage of this is that it summarizes access to password related attributes into a single DN that is not named for any special service such as libnss-ldap
    • unfortunatley the approach does not work with Samba because, unlike libnss-ldap, Samba does not use different DNs for accessing password related attributes and "normal" non-sensitive attributes
    • because Samba uses only a single DN, we would therefore be forced to give the hypothetical readonly-password DN rights to all other attributes of a user entry, as well as rights to read the ou=groups subtree to access Samba groups
    • since this is clearly against the purpose of the hypothetical readonly-password DN, this solution must also be considered not viable
  • create a DN cn=samba-service specifically for the use of the Samba service
    • this is the only possible alternative, or at least the only one that I can see that can provide us with clear and unambiguous ACLs

So what are the requirements for the new cn=samba-service DN?

  • read-only access to all "normal" non-sensitive attributes of entries below the ou=users subtree
  • since Samba does not need access to the userPassword attribute, the ACL for this attribute does not need to be relaxed
  • read+write access to basic password attributes sambaNTPassword and sambaLMPassword; write access because we want to be able to change the passwords through smbpasswd
  • read+write access to additional password attributes sambaPwdLastSet, sambaAcctFlags and sambaPasswordHistory which are also set by smbpasswd
  • read-only access to all attributes of entries below ou=groups subtree
  • read-only access to all attributes of entries below ou=samba subtree (this subtree will contain a sambaDomain entry that we manually move there after it's been automatically created by Samba; cf. chapter "Cleanup" further down)

See the OpenLDAP page for the actual ACLs.

Modify the LDAP directory


Existing entries in the LDAP directory that represent UNIX system users and groups need to be augmented with certain object classes and attributes so that they can also serve as Samba users and groups. The following sections provide details for this task.

The values for the password attributes sambaNTPassword and sambaLMPassword are hashes that need to be generated from the actual password. So far I have found only one way how to generate the value for sambaNTPassword (and none for sambaLMPassword): change the user's password interactively with smbpasswd. This requires that Samba is already configured for LDAP, therefore this step must wait until later.

In addition, a subtree ou=samba must be created. Later we will manually move a sambaDomain entry automatically created by Samba into this subtree.

Last but not least, the DN cn=samba-service,ou=users,dc=herzbube,dc=ch must be created. ACLs developed further up will refer to this DN, and Samba will be configured later on to use this DN.


User entries must follow these rules:

  • entry must have object class sambaSamAccount (an auxiliary object class)
  • user name must be stored in attribute cn
  • user ID must be stored in attribute uid
  • attribute sambaSID is a string that stores the user's "Security ID"
    • man smbldap-useradd defines this SID as: sid=$SID-rid, where $SID is the domain (=server) Security ID, and rid is the user ID
    • the sample entry created by smbldap-useradd has this attribute filled with "S-1-5-21-4037911697-1362994854-1556177682-7002"
    • at the time my system's SID was "S-1-5-21-4037911697-1362994854-1556177682"
    • this means that the user's rid is 7002
    • again from the man page: "For Samba users, rid is 2*uidNumber+1000"
    • for the sample user entry, which has an arbitrary uidNumber=3001, the calculation therefore goes: rid=2*3001+1000, which is indeed 7002
  • passwords
    • attribute sambaLMPassword is the user's LAN manager password
      • from one of the references listed at the top of the page: "The LM Hash is computed using the DES() algorithm. [...] The input is the password, in OEM Charset (8-bit) encoding, converted to upper case."
      • I have not yet found a way how to generate this hash
      • This is not grave, though, because it appears that sambaLMPassword is not needed for the services I am using Samba for
      • I have found indications (in /usr/share/doc/samba-tools/NEWS.Debian.gz) that Lanman authentication is only needed for Win95/98/ME clients and servers
    • attribute sambaNTPassword must contain an MD4 hash of the user's password in unicode
      • from one of the references listed at the top of the page: "The NT Hash is just the MD4() of the password. In this case, however, the password must be in Unicode (UCS2LE encoding)."
      • the sambaNTPassword hash can be set by running the following command as root:
smbpasswd <user>
      • for this to work, Samba must be configured for LDAP and have write access to the user entry
      • smbpasswd sets a number of additional attributes
      • sambaPwdLastSet = "1222377650"
      • sambaAcctFlags = "[U ]" (see Samba3-HOWTO for details)
      • sambaPasswordHistory = "0000000000000000000000000000000000000000000000000000000000000000" (see Samba3-HOWTO for details)
      • of these attributes, only sambaPwdLastSet is required (without this attribute, connections to Samba shares do not work!!!)
      • the other attributes can be manually removed, for instance to unclutter the appearance of the account entries
  • sambaPrimaryGroupSID = S-1-5-21-4037911697-1362994854-1556177682-7401
    • this refers to the SID of the user's primary group, see below for description of group entries


Group entries must follow these rules:

  • entry must have object class sambaGroupMapping (an auxiliary object class)
  • group name must be stored in attribute cn
  • group ID must be stored in attribute gidNumber
  • attribute sambaGroupType is an integer that stores the "NT Group Type"
    • the sample entry created by smbldap-groupadd has this attribute filled with "2"
  • attribute sambaSID is a string that stores the group's "Security ID"
    • man smbldap-groupadd defines this SID as: sid=$SID-rid, where $SID is the domain (=server) Security ID, and rid is the group ID
    • the sample entry created by smbldap-groupadd has this attribute filled with "S-1-5-21-4037911697-1362994854-1556177682-7401"
    • at the time my system's SID was "S-1-5-21-4037911697-1362994854-1556177682"
    • this means that the group's rid is 7401
    • again from the man page: "The rid of the group is calculated from the gidNumber of the group as rid=2*gidNumber+1001"
    • for the sample group entry, which has an arbitrary gidNumber=3200, the calculation therefore goes: rid=2*3200+1001, which is indeed 7401
  • attribute displayName is optional


Create the DN ou=samba,dc=herzbube,dc=ch. This entry forms a subtree into which we will later move a sambaDomain entry. That entry will be automatically created by Samba when it is restarted after its configuration has been changed to use LDAP.

Create Samba DN

Create the DN cn=samba-service,ou=users,dc=herzbube,dc=ch and give it a password.

Configure Samba to use LDAP

Add the following to /etc/samba/smb.conf:

   passdb backend = ldapsam:ldap://

   ldap admin dn = cn=samba-service,ou=users,dc=herzbube,dc=ch
   ldap group suffix = ou=groups
   ldap suffix = dc=herzbube,dc=ch
   ldap ssl = no
   ldap user suffix = ou=users

On the command line, specify the password for the DN specified for "ldap admin dn":

smbpasswd -w <ldap-secret>

The password will be stored in

pelargir:/var/lib/samba# ls -l secrets.tdb
-rw------- 1 root root 8192 Mar 25  2005 secrets.tdb

Note: smb.conf must already contain the LDAP configuration, otherwise smbpasswd -w will refuse to work.

Optimizing LDAP access

The option

ldapsam:trusted = yes

can be enabled in smb.conf to optimize LDAP access. By default this is turned off, which forces Samba to use the NSS subsystem to access POSIX user and group information. This causes two types of lookups to happen:

  • Samba looks up Samba-specific attributes via its own DN
  • Samba then asks NSS for POSIX information, which causes more lookups in the LDAP directory for the attributes posixAccount and posixGroup

If "ldapsam:trusted" is enabled, Samba will assume that the same LDAP objects that it queries to obtain Samba-specific attributes will also have the required POSIX attributes, thus drastically reducing the number of LDAP lookups.

I have made a short test, but with the current system setup it does not seem to work: After setting "ldapsam:trusted" to "yes" it is no longer possible to mount a Samba volume in Mac OS X. Maybe has something to do with the ACLs (although a quick review did not appear to prevent read-access to the necessary posixAccount and posixGroup attributes).

Activate the new configuration

Temporarily add write permission to Samba DN

Modify /etc/ldap/slapd.conf and temporarily add an ACL that gives write access for the directory base (dc=herzbube,dc=ch) to the Samba DN (cn=samba-service,ou=users,dc=herzbube,dc=ch).

Restart slapd for the new ACL to take effect.

Restart Samba

/etc/init.d/samba restart

The LDAP settings will now take effect. Samba will create an entry for the domain as a child to the DN specified for "ldap suffix". For instance, in my case I got an entry with DN sambaDomainName=PELARGIR,dc=herzbube,dc=ch. The interesting thing about this entry is the attribute SID. It contains the same SID that was used to setup user and group entries in a previous configuration step.

Remove write permission from Samba DN

Remove the ACL that temporarily gave write access to Samba to the directory base from /etc/ldap/slapd.conf.

Restart slapd for the ACL change to take effect.

Set user passwords

Use this command to set the NT passwords for Samba user accounts.

smbpasswd <user>


  • must be run as root
  • the ACLs that allow Samba to write to password-related attributes must be in place (see the chapter further up where ACLs are developed)
  • sets the following attributes that are required to connect to a Samba share:
    • sambaNTPassword
    • sambaPwdLastSet
  • also sets the following attributes that can be manually removed after the password change
    • sambaAcctFlags
    • sambaPasswordHistory


Move sambaDomain entry

To remove clutter from the base DN dc=herzbube,dc=ch, manually move the entry with DN sambaDomainName=PELARGIR,dc=herzbube,dc=ch to below the subtree ou=samba,dc=herzbube,dc=ch. It appears that this works because Samba does not search for the sambaDomain entry in a specific subtree, but instead starts its search in the LDAP directory root. I do not expect this to have much negative impact because I do not expect many Samba connections. Hopefully, proper indexing will also reduce search time.

Remove old password file

Accounts are now managed in LDAP, so they can be removed from the place they were originally kept in. Since I was using "passdb backend = tdbsam" in my smb.conf before changing to LDAP, account information have been stored in the file passdb.tdb located in /var/lib/samba on my machine.

I simply deleted the file:

rm /var/lib/samba/passdb.tdb



The Debian package smbldap-tools provides a couple of perl scripts that can be used to populate/manipulate the LDAP directory. I have used these tools for initial experiments, however I soon removed the package after I finished the Samba/LDAP integration job because I prefer phpLDAPadmin to perform administration tasks in the LDAP directory. Also, having these tools around requires another set of configuration files to be maintained and protected because they contain a password.

Installing the smbldap-tools Debian package adds the following command line utilities:





For these utilities to work, there must be a configuration in /etc/smbldap-tools/smbldap.conf and /etc/smbldap-tools/smbldap_bind.conf.


  • copy sample file
cp /usr/share/doc/smbldap-tools/examples/smbldap.conf.gz /etc/smbldap-tools
cd /etc/smbldap-tools
gunzip smbldap.conf.gz
  • suffix="dc=herzbube,dc=ch"
  • usersdn="ou=testusers,${suffix}"
  • groupsdn="ou=testgroups,${suffix}"
  • determine the SID by executing this on the command line
net getlocalsid
  • SID="<sid>"
  • comment out the sambaDomain option (will be taken from smb.conf
  • fix permissions
chmod 0644 /etc/smbldap-tools/smbldap.conf


  • copy sample file
cp /usr/share/doc/smbldap-tools/examples/smbldap_bind.conf /etc/smbldap-tools/smbldap_bind.conf
  • slaveDN="cn=admin,ou=users,dc=herzbube,dc=ch"
  • slavePw = secret
  • masterDN="cn=admin,ou=users,dc=herzbube,dc=ch"
  • masterPw = secret
  • fix permissions
chmod 0600 /etc/smbldap-tools/smbldap_bind.conf

Basic usage

Add a group

smbldap-groupadd -g 3200 -a sambagroup


group ID
calculate an automatic Security ID (SID)
the group name

Add a user

smbldap-useradd -a -u 3000 -g 3200 sambauser

Discussion of parameters:

make it a Samba account
user id
user name

Working with .tdb files

Samba uses the Trivial Database format to store information in .tdb files. For instance, the password to use for accessing the LDAP directory is stored in secrets.db. On my machine, some (if not all) of Samba's .tdb files are stored in /var/lib/samba.

To work with .tdb files you need to install the Debian package


It provides the following command line utilities

  • tdbdump : to list the content of a .tdb file
  • tdbtool : to manipulate a database interactively (run the command, and enter "?" on the following command prompt)

The utility tdbbackup is part of the samba package itself.

Mac OS X


Newer versions of Mac OS X

At least for Mac OS X 10.5, a Samba server automatically appears in the Finder's side bar. Click on the server to see the available shares, then click on a share to connect. If you need to specify credentials you can allow them to be stored in your keychain so that the next time you try to access the share, authentication will happen automatically.

Older versions of Mac OS X

In the Finder, navigate to

  • Network
  • pelargir

Click the "connect" button. On some versions of Mac OS X, the Finder may now hang itself. To solve this problem, either

  • use an alternative program to mount the share (e.g. "SMB Browser")
  • or use the "goto folder" option in the Finder and enter the direct URL (I have not tested this)

Problems with permissions

Recently I noticed strange behaviour when copying files from/to a Samba share in the Finder. Files would not retain their permissions at all when they were copied to a Samba share, and then back on a HFS volume. Resources on the net suggest that the problems (the symptoms of which I am going to describe in a minute) are connected to the Samba feature "UNIX extensions". The Samba client on the Mac OS X side apparently implements this feature only since Mac OS X 10.5. Although I am not absolutely sure, I would say that my problems indeed cropped up only recently, so my own experiences might support that theory.

I made some experiments with the "UNIX extensions" feature turned on and off on the Samba server. The following table shows what happens when Finder or cp are used for copying files.

UNIX extensions Source file permissions on the HFS volume File permissions when copying with Finder File permissions when copying with cp Remarks
On Samba share, seen from the client On Samba share, seen from the server Back on HFS volume On Samba share, seen from the client On Samba share, seen from the server Back on HFS volume
yes --------- (000) --------- (000) --------- (000) --------- (000) --------- (000) --------- (000) - (copying back was impossible) Both Finder and cp are OK
yes --x--x--x (111) --x--x--x (111) --x--x--x (111) --x--x--x (111) --x--x--x (111) --x--x--x (111) - (copying back was impossible) Both Finder and cp are OK
yes -w--w--w- (222) -w--w--w- (222) -w--w--w- (222) -w--w--w- (222) -w------- (200) -w------- (200) - (copying back was impossible) Finder is OK; cp loses permissions for group/other
yes -wx-wx-wx (333) -wx-wx-wx (333) -wx-wx-wx (333) -wx-wx-wx (333) -wx--x--x (311) -wx--x--x (311) - (copying back was impossible) Finder is OK; cp loses write permission for group/other
yes r--r--r-- (444) r--r--r-- (444) r--r--r-- (444) r--r--r-- (444) r--r--r-- (444) r--r--r-- (444) r--r--r-- (444) Both Finder and cp are OK
yes r-xr-xr-x (555) r-xr-xr-x (555) r-xr-xr-x (555) r-xr-xr-x (555) r-xr-xr-x (555) r-xr-xr-x (555) r-xr-xr-x (555) Both Finder and cp are OK
yes rw-rw-rw- (666) rw-rw-rw- (666) rw-rw-rw- (666) rw-rw-rw- (666) rwx------ (700) rwx------ (700) rwx------ (700) Finder is OK; cp loses permissions for group/other and adds executable bit on owner
yes rwxrwxrwx (777) rw-rwxrwx (677) rw-rwxrwx (677) rw-rwxrwx (677) rwx------ (700) rwx------ (700) rwx------ (700) Finder loses executable bit for owner; cp loses permissions for group/other
no any rwx------ (700) rwx------ (700) rwx------ (700) rwx------ (700) rwx------ (700) rwx------ (700) Whatever the original permissions, both Finder and cp lose all permissions; permissions are set to how the Samba server is configured


  • copying of files for which the owner has no read permission (modes 0-3, where bit 4 is not set) does not properly work even in Finder; Finder creates the files on the Samba side but is then unable to copy the files' content, so they remain empty
  • I have not tested directories because for initial analysis I am interested in files
  • when UNIX extensions are off, files are bluntly assigned the 700 permission set because I have configured Samba to use 700 both for "create mask" and "directory mask"
  • when UNIX extensions are on, cp appears to behave wildly erratic; this needs further analysis
  • the behaviour of Finder is almost OK; the only glitch is when it loses the owner's executable bit when the owner permissions are 7 (all bits are set)


  • do NOT use cp for copying files
  • do NOT use Finder for copying executable files; this affects .app bundles, so it's best to copy those inside container files (.dmg, .zip, etc.)
  • copying directories with Finder seems to be OK, a quick non-conclusive test showed that directories with permissions 755 and 777 are copied correctly
  • make further investigations (see Bugzilla issue)

swat configuration

swat is no longer supported upstream, and Debian no longer distributes the tool. The information in this section is purely historical.

Initial notes

  • swat requires authentication with username "root" and the corresponding password
  • swat communicates over plain HTTP, not the secure HTTPS, which means that the password (and this is the root password!) is transmitted over the network in clear text
  • Port 901 is reserved for communication with swat

Unsecure configuration

Before reading any further: This section outlines a simple and rather unsecure configuration for swat. I keep this information only for historical reasons, and for sake of a better understanding why/how the secure, proxied is better.

swat is activated by the inetd daemon, therefore we must add a proper entry to /etc/inetd.confy. This must be done manually, the entry is not configured automatically during package installation for security reasons (at least that's what the man page tells us). This is how the line looks like on my system:

localhost:swat   stream   tcp   nowait.400   root   /usr/sbin/tcpd   /usr/sbin/swat

By naming the service swat, we tell inetd to listen on port 901 (see /etc/services for the "swat" entry). Also note the prefix "localhost:" - this prefix tells inetd to only listen for connections coming in from localhost, but not for connections coming from any of the outward pointing network interfaces. This is done for security reasons (because passwords are transmitted in the clear via HTTP), but remote access is no longer possible because of this.

Note on upgrading the Samba Debian packages: When I did such an update in March 2010, the package configuration process automatically added another entry for swat to /etc/inetd.conf . This second entry did not have the localhost prefix, i.e. with this line inetd would have tried to listen on all network interfaces! I found out about this because inetd wrote a warning to the system log about the port 901 being already in use on (by the Apache daemon, obviously). To fix the issue I manually removed the line.

Secure configuration

Since swat cannot be taught HTTPS, we simply hide the swat port behind an Apache reverse proxy. The inetd.conf configuration which allows connections only from localhost now makes perfect sense: Secure HTTPS remote access is now possible via port 901 on any of the outward pointing network interfaces, and Apache simply forwards traffic to http://localhost:901, translating from HTTPS to HTTP in the process.

To make this work, add the following configuration snippets to the Apache configuration:

  • To /etc/apache2/conf.d/pelargir.conf:
  • To /etc/apache2/conf.d/pelargir-ssl.conf:
  • To /etc/apache2/sites-available/
# --------------------------------------------------------------------------------
# SSL reverse proxy to protect swat
# Note 1: We listen on because this allows us to connect to a public
# DNS name, such as, that is matched by the SSL certificate.
# If we would listen on we could connect only to *,
# which is NOT matched by the SSL cert and would result in an upsetting browser
# warning. In order to protect the swat port (901) from access from the public
# Internet, we rely on the ADSL router to not forward traffic to that port.
# Note 2: Despite the above note, we don't use ServerName or ServerAlias, because
# we want this Virtual Host to match all queries on port 901.
# --------------------------------------------------------------------------------
<IfModule mod_ssl.c>
    ErrorLog /var/log/apache2/
    CustomLog /var/log/apache2/ combined

    DocumentRoot /var/www/unknown

    SSLEngine on
    SSLCertificateFile /etc/ssl/certs/
    SSLCertificateKeyFile /etc/ssl/private/
    SSLCertificateChainFile /etc/ssl/certs/
    SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown

    # ----- swat -----
    <IfModule mod_proxy.c>
      # Rely on the general configuration file having enabled the
      # reverse proxy through the "ProxyRequests Off" directive
      ProxyPass / http://localhost:901/
      ProxyPassReverse / http://localhost:901/
      <Location />
        Require all granted

To activate the setup:

apache2ctl restart
kill -SIGHUP <inetd pid>

Access is now possible in the web browser through this URL: