From 48578bd4925a675bf30d4f2452f147c3ee11154f Mon Sep 17 00:00:00 2001 From: Stefan Metzmacher Date: Thu, 11 Sep 2008 16:50:49 +0200 Subject: add '4' to the end of some filesnames metze --- BUGS.txt | 24 -- BUGS4.txt | 24 ++ NEWS | 508 ------------------------------------ NEWS4 | 508 ++++++++++++++++++++++++++++++++++++ TODO | 278 -------------------- TODO4 | 278 ++++++++++++++++++++ WHATSNEW.txt | 146 ----------- WHATSNEW4.txt | 146 +++++++++++ howto.txt | 188 -------------- howto4.txt | 188 ++++++++++++++ prog_guide.txt | 789 -------------------------------------------------------- prog_guide4.txt | 789 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 12 files changed, 1933 insertions(+), 1933 deletions(-) delete mode 100644 BUGS.txt create mode 100644 BUGS4.txt delete mode 100644 NEWS create mode 100644 NEWS4 delete mode 100644 TODO create mode 100644 TODO4 delete mode 100644 WHATSNEW.txt create mode 100644 WHATSNEW4.txt delete mode 100644 howto.txt create mode 100644 howto4.txt delete mode 100644 prog_guide.txt create mode 100644 prog_guide4.txt diff --git a/BUGS.txt b/BUGS.txt deleted file mode 100644 index 1a9790ddd9f..00000000000 --- a/BUGS.txt +++ /dev/null @@ -1,24 +0,0 @@ -Samba4 alpha4 is not a final Samba release. That is more a reference -to Samba4's lack of the features we expect you will need than a -statement of code quality, but clearly it hasn't seen a broad -deployment yet. If you were to upgrade Samba3 (or indeed Windows) to -Samba4, you would find many things work, but that other key features -you may have relied on simply are not there yet. - -For example, while Samba 3.0 is an excellent member of a Active -Directory domain, Samba4 is happier as a domain controller, and it is -in this role where it has seen deployment into production. - -Samba4 is subjected to an awesome battery of tests on an -automated basis, we have found Samba4 to be very stable in it's -behaviour. We have to recommend against upgrading production servers -from Samba 3 to Samba 4 at this stage, because there may be the features on -which you may rely that are not present, or the mapping of -your configuration and user database may not be complete. - -If you are upgrading, or looking to develop, test or deploy Samba4, you should -backup all configuration and data. - -We welcome your testing, please file bug reports at -https://bugzilla.samba.org/, product: Samba4. Please include as much -information as possible, such as GIT revision number and backtraces. diff --git a/BUGS4.txt b/BUGS4.txt new file mode 100644 index 00000000000..1a9790ddd9f --- /dev/null +++ b/BUGS4.txt @@ -0,0 +1,24 @@ +Samba4 alpha4 is not a final Samba release. That is more a reference +to Samba4's lack of the features we expect you will need than a +statement of code quality, but clearly it hasn't seen a broad +deployment yet. If you were to upgrade Samba3 (or indeed Windows) to +Samba4, you would find many things work, but that other key features +you may have relied on simply are not there yet. + +For example, while Samba 3.0 is an excellent member of a Active +Directory domain, Samba4 is happier as a domain controller, and it is +in this role where it has seen deployment into production. + +Samba4 is subjected to an awesome battery of tests on an +automated basis, we have found Samba4 to be very stable in it's +behaviour. We have to recommend against upgrading production servers +from Samba 3 to Samba 4 at this stage, because there may be the features on +which you may rely that are not present, or the mapping of +your configuration and user database may not be complete. + +If you are upgrading, or looking to develop, test or deploy Samba4, you should +backup all configuration and data. + +We welcome your testing, please file bug reports at +https://bugzilla.samba.org/, product: Samba4. Please include as much +information as possible, such as GIT revision number and backtraces. diff --git a/NEWS b/NEWS deleted file mode 100644 index 8a63719a0ed..00000000000 --- a/NEWS +++ /dev/null @@ -1,508 +0,0 @@ -This file aims to document the major changes since the latest released version -of Samba, 3.0. Samba 4.0 contains rewrites of several subsystems -and uses a different internal format for most data. Since this -file is an initial draft, please update missing items. - -One of the main goals of Samba 4 was Active Directory Domain Controller -support. This means Samba now implements several protocols that are required -by AD such as Kerberos and DNS. - -An (experimental) upgrade script that performs a one-way upgrade -from Samba 3 is available in source/setup/upgrade. - -Removal of nmbd and introduction of process models -================================================== -smbd now implements several network protocols other than just CIFS and -DCE/RPC. nmbd's functionality has been merged into smbd. smbd supports -various 'process models' that specify how concurrent connections are -handled (when to fork, use threads, etc). - -Introduction of LDB -=================== -Samba now stores most of its persistent data in a LDAP-like database -called LDB (see ldb(7) for more info). - -Removed SWAT -================== -Unlike previous versions, Samba4 does not provide a web interface at this time. - -Built-in KDC -============ -Samba4 ships with an integrated KDC (Kerberos Key Distribution -Center). Backed directly onto our main internal database, and -integrated with custom code to handle the PAC, Samba4's KDC is an -integral part of our support for AD logon protocols. - -Built-in LDAP Server -==================== -Like the situation with the KDC, Samba4 ships with it's own LDAP -server, included to provide simple, built-in LDAP services in an AD -(rather than distinctly standards) matching manner. The database is -LDB, and it shares that in common with the rest of Samba. - -Changed configuration options -============================= -Several configuration options have been removed in Samba4 while others have -been introduced. This section contains a summary of changes to smb.conf and -where these settings moved. Configuration options that have disappeared may be -re-added later when the functionality that uses them gets reimplemented in -Samba 4. - -The 'security' parameter has been split up. It is now only used to choose -between the 'user' and 'share' security levels (the latter is not supported -in Samba 4 yet). The other values of this option and the 'domain master' and -'domain logons' parameters have been merged into a 'server role' parameter -that can be either 'domain controller', 'member server' or 'standalone'. Note that -member server support does not work yet. - -The following parameters have been removed: -- passdb backend: accounts are now stored in a LDB-based SAM database, - see 'sam database' below. -- update encrypted -- public -- guest ok -- client schannel -- server schannel -- allow trusted domains -- hosts equiv -- map to guest -- smb passwd file -- algorithmic rid base -- root directory -- root dir -- root -- guest account -- enable privileges -- pam password change -- passwd program -- passwd chat debug -- passwd chat timeout -- check password script -- username map -- username level -- unix password sync -- restrict anonymous -- username -- user -- users -- invalid users -- valid users -- admin users -- read list -- write list -- printer admin -- force user -- force group -- group -- write ok -- writeable -- writable -- acl check permissions -- acl group control -- acl map full control -- create mask -- create mode -- force create mode -- security mask -- force security mode -- directory mask -- directory mode -- force directory mode -- directory security mask -- force directory security mode -- force unknown acl user -- inherit permissions -- inherit acls -- inherit owner -- guest only -- only guest -- only user -- allow hosts -- deny hosts -- preload modules -- use kerberos keytab -- syslog -- syslog only -- max log size -- debug timestamp -- timestamp logs -- debug hires timestamp -- debug pid -- debug uid -- allocation roundup size -- aio read size -- aio write size -- aio write behind -- large readwrite -- protocol -- read bmpx -- reset on zero vc -- acl compatibility -- defer sharing violations -- ea support -- nt acl support -- nt pipe support -- profile acls -- map acl inherit -- afs share -- max ttl -- client use spnego -- enable asu support -- svcctl list -- block size -- change notify timeout -- deadtime -- getwd cache -- keepalive -- kernel change notify -- lpq cache time -- max smbd processes -- max disk size -- max open files -- min print space -- strict allocate -- sync always -- use mmap -- use sendfile -- hostname lookups -- write cache size -- name cache timeout -- max reported print jobs -- load printers -- printcap cache time -- printcap name -- printcap -- printing -- cups options -- cups server -- iprint server -- print command -- disable spoolss -- enable spoolss -- lpq command -- lprm command -- lppause command -- lpresume command -- queuepause command -- queueresume command -- enumports command -- addprinter command -- deleteprinter command -- show add printer wizard -- os2 driver map -- use client driver -- default devmode -- force printername -- mangling method -- mangle prefix -- default case -- case sensitive -- casesignames -- preserve case -- short preserve case -- mangling char -- hide dot files -- hide special files -- hide unreadable -- hide unwriteable files -- delete veto files -- veto files -- hide files -- veto oplock files -- map readonly -- mangled names -- mangled map -- max stat cache size -- stat cache -- store dos attributes -- machine password timeout -- add user script -- rename user script -- delete user script -- add group script -- delete group script -- add user to group script -- delete user from group script -- set primary group script -- add machine script -- shutdown script -- abort shutdown script -- username map script -- logon script -- logon path -- logon drive -- logon home -- domain logons -- os level -- lm announce -- lm interval -- domain master -- browse list -- enhanced browsing -- wins proxy -- wins hook -- wins partners -- blocking locks -- fake oplocks -- kernel oplocks -- locking -- lock spin count -- lock spin time -- level2 oplocks -- oplock break wait time -- oplock contention limit -- posix locking -- share modes -- ldap server -- ldap port -- ldap admin dn -- ldap delete dn -- ldap group suffix -- ldap idmap suffix -- ldap machine suffix -- ldap passwd sync -- ldap password sync -- ldap replication sleep -- ldap suffix -- ldap ssl -- ldap timeout -- ldap page size -- ldap user suffix -- add share command -- change share command -- delete share command -- eventlog list -- utmp directory -- wtmp directory -- utmp -- default service -- default -- message command -- dfree cache time -- dfree command -- get quota command -- set quota command -- remote announce -- remote browse sync -- homedir map -- afs username map -- afs token lifetime -- log nt token command -- time offset -- NIS homedir -- preexec -- exec -- preexec close -- postexec -- root preexec -- root preexec close -- root postexec -- set directory -- wide links -- follow symlinks -- dont descend -- magic script -- magic output -- delete readonly -- dos filemode -- dos filetimes -- dos filetime resolution -- fake directory create times -- panic action -- vfs objects -- vfs object -- msdfs root -- msdfs proxy -- host msdfs -- enable rid algorithm -- passdb expand explicit -- idmap backend -- idmap uid -- winbind uid -- idmap gid -- winbind gid -- template homedir -- template shell -- winbind separator -- winbind cache time -- winbind enum users -- winbind enum groups -- winbind use default domain -- winbind trusted domains only -- winbind nested groups -- winbind max idle children -- winbind nss info - -The following parameters have been added: -+ rpc big endian (G) - Make Samba fake it is running on a bigendian machine when using DCE/RPC. - Useful for debugging. - - Default: no - -+ case insensitive filesystem (S) - Set to true if this share is located on a case-insensitive filesystem. - This disables looking for a filename by trying all possible combinations of - uppercase/lowercase characters and thus speeds up operations when a - file cannot be found. - - Default: no - -+ js include (G) - Path to JavaScript library. - - Default: Set at compile-time - -+ setup directory - Path to data used by provisioning script. - - Default: Set at compile-time - -+ ncalrpc dir - Directory to use for UNIX sockets used by the 'ncalrpc' DCE/RPC transport. - - Default: Set at compile-time - -+ ntvfs handler - Backend to the NT VFS to use (more than one can be specified). Available - backends include: - - - posix: - Maps POSIX FS semantics to NT semantics - - - simple: - Very simple backend (original testing backend). - - - unixuid: - Sets up user credentials based on POSIX gid/uid. - - - cifs: - Proxies a remote CIFS FS. Mainly useful for testing. - - - nbench: - Filter module that saves data useful to the nbench benchmark suite. - - - ipc: - Allows using SMB for inter process communication. Only used for - the IPC$ share. - - - print: - Allows printing over SMB. This is LANMAN-style printing (?), not - the be confused with the spoolss DCE/RPC interface used by later - versions of Windows. - - Default: unixuid default - -+ ntptr providor - FIXME - -+ dcerpc endpoint servers - What DCE/RPC servers to start. - - Default: epmapper srvsvc wkssvc rpcecho samr netlogon lsarpc spoolss drsuapi winreg dssetup - -+ server services - Services Samba should provide. - - Default: smb rpc nbt wrepl ldap cldap web kdc - -+ sam database - Location of the SAM (account database) database. This should be a - LDB URL. - - Default: set at compile-time - -+ spoolss database - Spoolss (printer) DCE/RPC server database. This should be a LDB URL. - - Default: set at compile-time - -+ wins config database - WINS configuration database location. This should be a LDB URL. - - Default: set at compile-time - -+ wins database - WINS database location. This should be a LDB URL. - - Default: set at compile-time - -+ client use spnego principal - Tells the client to use the Kerberos service principal specified by the - server during the security protocol negotation rather than - looking up the principal itself (cifs/hostname). - - Default: false - -+ nbt port - TCP/IP Port used by the NetBIOS over TCP/IP (NBT) implementation. - - Default: 137 - -+ dgram port - UDP/IP port used by the NetBIOS over TCP/IP (NBT) implementation. - - Default: 138 - -+ cldap port - UDP/IP port used by the CLDAP protocol. - - Default: 389 - -+ krb5 port - IP port used by the kerberos KDC. - - Default: 88 - -+ kpasswd port - IP port used by the kerberos password change protocol. - - Default: 464 - -+ web port - TCP/IP port SWAT should listen on. - - Default: 901 - -+ tls enabled - Enable TLS support for SWAT - - Default: true - -+ tls keyfile - Path to TLS key file (PEM format) to be used by SWAT. If no - path is specified, Samba will create a key. - - Default: none - -+ tls certfile - Path to TLS certificate file (PEM format) to be used by SWAT. If no - path is specified, Samba will create a certificate. - - Default: none - -+ tls cafile - Path to CA authority file Samba will use to sign TLS keys it generates. If - no path is specified, Samba will create a self-signed CA certificate. - - Default: none - -+ tls crlfile - Path to TLS certificate revocation lists file. - - Default: none - -+ swat directory - SWAT data directory. - - Default: set at compile-time - -+ large readwrite - Indicate the CIFS server is able to do large reads/writes. - - Default: true - -+ unicode - Enable/disable unicode support in the protocol. - - Default: true diff --git a/NEWS4 b/NEWS4 new file mode 100644 index 00000000000..8a63719a0ed --- /dev/null +++ b/NEWS4 @@ -0,0 +1,508 @@ +This file aims to document the major changes since the latest released version +of Samba, 3.0. Samba 4.0 contains rewrites of several subsystems +and uses a different internal format for most data. Since this +file is an initial draft, please update missing items. + +One of the main goals of Samba 4 was Active Directory Domain Controller +support. This means Samba now implements several protocols that are required +by AD such as Kerberos and DNS. + +An (experimental) upgrade script that performs a one-way upgrade +from Samba 3 is available in source/setup/upgrade. + +Removal of nmbd and introduction of process models +================================================== +smbd now implements several network protocols other than just CIFS and +DCE/RPC. nmbd's functionality has been merged into smbd. smbd supports +various 'process models' that specify how concurrent connections are +handled (when to fork, use threads, etc). + +Introduction of LDB +=================== +Samba now stores most of its persistent data in a LDAP-like database +called LDB (see ldb(7) for more info). + +Removed SWAT +================== +Unlike previous versions, Samba4 does not provide a web interface at this time. + +Built-in KDC +============ +Samba4 ships with an integrated KDC (Kerberos Key Distribution +Center). Backed directly onto our main internal database, and +integrated with custom code to handle the PAC, Samba4's KDC is an +integral part of our support for AD logon protocols. + +Built-in LDAP Server +==================== +Like the situation with the KDC, Samba4 ships with it's own LDAP +server, included to provide simple, built-in LDAP services in an AD +(rather than distinctly standards) matching manner. The database is +LDB, and it shares that in common with the rest of Samba. + +Changed configuration options +============================= +Several configuration options have been removed in Samba4 while others have +been introduced. This section contains a summary of changes to smb.conf and +where these settings moved. Configuration options that have disappeared may be +re-added later when the functionality that uses them gets reimplemented in +Samba 4. + +The 'security' parameter has been split up. It is now only used to choose +between the 'user' and 'share' security levels (the latter is not supported +in Samba 4 yet). The other values of this option and the 'domain master' and +'domain logons' parameters have been merged into a 'server role' parameter +that can be either 'domain controller', 'member server' or 'standalone'. Note that +member server support does not work yet. + +The following parameters have been removed: +- passdb backend: accounts are now stored in a LDB-based SAM database, + see 'sam database' below. +- update encrypted +- public +- guest ok +- client schannel +- server schannel +- allow trusted domains +- hosts equiv +- map to guest +- smb passwd file +- algorithmic rid base +- root directory +- root dir +- root +- guest account +- enable privileges +- pam password change +- passwd program +- passwd chat debug +- passwd chat timeout +- check password script +- username map +- username level +- unix password sync +- restrict anonymous +- username +- user +- users +- invalid users +- valid users +- admin users +- read list +- write list +- printer admin +- force user +- force group +- group +- write ok +- writeable +- writable +- acl check permissions +- acl group control +- acl map full control +- create mask +- create mode +- force create mode +- security mask +- force security mode +- directory mask +- directory mode +- force directory mode +- directory security mask +- force directory security mode +- force unknown acl user +- inherit permissions +- inherit acls +- inherit owner +- guest only +- only guest +- only user +- allow hosts +- deny hosts +- preload modules +- use kerberos keytab +- syslog +- syslog only +- max log size +- debug timestamp +- timestamp logs +- debug hires timestamp +- debug pid +- debug uid +- allocation roundup size +- aio read size +- aio write size +- aio write behind +- large readwrite +- protocol +- read bmpx +- reset on zero vc +- acl compatibility +- defer sharing violations +- ea support +- nt acl support +- nt pipe support +- profile acls +- map acl inherit +- afs share +- max ttl +- client use spnego +- enable asu support +- svcctl list +- block size +- change notify timeout +- deadtime +- getwd cache +- keepalive +- kernel change notify +- lpq cache time +- max smbd processes +- max disk size +- max open files +- min print space +- strict allocate +- sync always +- use mmap +- use sendfile +- hostname lookups +- write cache size +- name cache timeout +- max reported print jobs +- load printers +- printcap cache time +- printcap name +- printcap +- printing +- cups options +- cups server +- iprint server +- print command +- disable spoolss +- enable spoolss +- lpq command +- lprm command +- lppause command +- lpresume command +- queuepause command +- queueresume command +- enumports command +- addprinter command +- deleteprinter command +- show add printer wizard +- os2 driver map +- use client driver +- default devmode +- force printername +- mangling method +- mangle prefix +- default case +- case sensitive +- casesignames +- preserve case +- short preserve case +- mangling char +- hide dot files +- hide special files +- hide unreadable +- hide unwriteable files +- delete veto files +- veto files +- hide files +- veto oplock files +- map readonly +- mangled names +- mangled map +- max stat cache size +- stat cache +- store dos attributes +- machine password timeout +- add user script +- rename user script +- delete user script +- add group script +- delete group script +- add user to group script +- delete user from group script +- set primary group script +- add machine script +- shutdown script +- abort shutdown script +- username map script +- logon script +- logon path +- logon drive +- logon home +- domain logons +- os level +- lm announce +- lm interval +- domain master +- browse list +- enhanced browsing +- wins proxy +- wins hook +- wins partners +- blocking locks +- fake oplocks +- kernel oplocks +- locking +- lock spin count +- lock spin time +- level2 oplocks +- oplock break wait time +- oplock contention limit +- posix locking +- share modes +- ldap server +- ldap port +- ldap admin dn +- ldap delete dn +- ldap group suffix +- ldap idmap suffix +- ldap machine suffix +- ldap passwd sync +- ldap password sync +- ldap replication sleep +- ldap suffix +- ldap ssl +- ldap timeout +- ldap page size +- ldap user suffix +- add share command +- change share command +- delete share command +- eventlog list +- utmp directory +- wtmp directory +- utmp +- default service +- default +- message command +- dfree cache time +- dfree command +- get quota command +- set quota command +- remote announce +- remote browse sync +- homedir map +- afs username map +- afs token lifetime +- log nt token command +- time offset +- NIS homedir +- preexec +- exec +- preexec close +- postexec +- root preexec +- root preexec close +- root postexec +- set directory +- wide links +- follow symlinks +- dont descend +- magic script +- magic output +- delete readonly +- dos filemode +- dos filetimes +- dos filetime resolution +- fake directory create times +- panic action +- vfs objects +- vfs object +- msdfs root +- msdfs proxy +- host msdfs +- enable rid algorithm +- passdb expand explicit +- idmap backend +- idmap uid +- winbind uid +- idmap gid +- winbind gid +- template homedir +- template shell +- winbind separator +- winbind cache time +- winbind enum users +- winbind enum groups +- winbind use default domain +- winbind trusted domains only +- winbind nested groups +- winbind max idle children +- winbind nss info + +The following parameters have been added: ++ rpc big endian (G) + Make Samba fake it is running on a bigendian machine when using DCE/RPC. + Useful for debugging. + + Default: no + ++ case insensitive filesystem (S) + Set to true if this share is located on a case-insensitive filesystem. + This disables looking for a filename by trying all possible combinations of + uppercase/lowercase characters and thus speeds up operations when a + file cannot be found. + + Default: no + ++ js include (G) + Path to JavaScript library. + + Default: Set at compile-time + ++ setup directory + Path to data used by provisioning script. + + Default: Set at compile-time + ++ ncalrpc dir + Directory to use for UNIX sockets used by the 'ncalrpc' DCE/RPC transport. + + Default: Set at compile-time + ++ ntvfs handler + Backend to the NT VFS to use (more than one can be specified). Available + backends include: + + - posix: + Maps POSIX FS semantics to NT semantics + + - simple: + Very simple backend (original testing backend). + + - unixuid: + Sets up user credentials based on POSIX gid/uid. + + - cifs: + Proxies a remote CIFS FS. Mainly useful for testing. + + - nbench: + Filter module that saves data useful to the nbench benchmark suite. + + - ipc: + Allows using SMB for inter process communication. Only used for + the IPC$ share. + + - print: + Allows printing over SMB. This is LANMAN-style printing (?), not + the be confused with the spoolss DCE/RPC interface used by later + versions of Windows. + + Default: unixuid default + ++ ntptr providor + FIXME + ++ dcerpc endpoint servers + What DCE/RPC servers to start. + + Default: epmapper srvsvc wkssvc rpcecho samr netlogon lsarpc spoolss drsuapi winreg dssetup + ++ server services + Services Samba should provide. + + Default: smb rpc nbt wrepl ldap cldap web kdc + ++ sam database + Location of the SAM (account database) database. This should be a + LDB URL. + + Default: set at compile-time + ++ spoolss database + Spoolss (printer) DCE/RPC server database. This should be a LDB URL. + + Default: set at compile-time + ++ wins config database + WINS configuration database location. This should be a LDB URL. + + Default: set at compile-time + ++ wins database + WINS database location. This should be a LDB URL. + + Default: set at compile-time + ++ client use spnego principal + Tells the client to use the Kerberos service principal specified by the + server during the security protocol negotation rather than + looking up the principal itself (cifs/hostname). + + Default: false + ++ nbt port + TCP/IP Port used by the NetBIOS over TCP/IP (NBT) implementation. + + Default: 137 + ++ dgram port + UDP/IP port used by the NetBIOS over TCP/IP (NBT) implementation. + + Default: 138 + ++ cldap port + UDP/IP port used by the CLDAP protocol. + + Default: 389 + ++ krb5 port + IP port used by the kerberos KDC. + + Default: 88 + ++ kpasswd port + IP port used by the kerberos password change protocol. + + Default: 464 + ++ web port + TCP/IP port SWAT should listen on. + + Default: 901 + ++ tls enabled + Enable TLS support for SWAT + + Default: true + ++ tls keyfile + Path to TLS key file (PEM format) to be used by SWAT. If no + path is specified, Samba will create a key. + + Default: none + ++ tls certfile + Path to TLS certificate file (PEM format) to be used by SWAT. If no + path is specified, Samba will create a certificate. + + Default: none + ++ tls cafile + Path to CA authority file Samba will use to sign TLS keys it generates. If + no path is specified, Samba will create a self-signed CA certificate. + + Default: none + ++ tls crlfile + Path to TLS certificate revocation lists file. + + Default: none + ++ swat directory + SWAT data directory. + + Default: set at compile-time + ++ large readwrite + Indicate the CIFS server is able to do large reads/writes. + + Default: true + ++ unicode + Enable/disable unicode support in the protocol. + + Default: true diff --git a/TODO b/TODO deleted file mode 100644 index 14df8a507a0..00000000000 --- a/TODO +++ /dev/null @@ -1,278 +0,0 @@ -source/build/smb_build/TODO -source/lib/registry/TODO -source/lib/tdr/TODO -source/pidl/TODO - -- seperate adminlog mechanism (as opposed to the current DEBUG log, - which is not really aimed at administrators but more at developers) - Perhaps similar to eventlog so we can also use eventlog to retrieve the data? - -- testsuite for the 'net' tool - -- and a lot of other stuff - -Configuration options -===================== - -The following options don't exist in Samba4 yet -or are not converted by the upgrade script -or will be removed: - -- update encrypted -- public -- guest ok -- client schannel -- server schannel -- allow trusted domains -- hosts equiv -- map to guest -- algorithmic rid base -- root directory -- root dir -- root -- guest account -- enable privileges -- pam password change -- passwd program -- passwd chat debug -- passwd chat timeout -- check password script -- username map -- username level -- unix password sync -- restrict anonymous -- username -- user -- users -- invalid users -- valid users -- admin users -- read list -- write list -- printer admin -- force user -- force group -- group -- write ok -- writeable -- writable -- acl check permissions -- acl group control -- acl map full control -- create mask -- create mode -- force create mode -- security mask -- force security mode -- directory mask -- directory mode -- force directory mode -- directory security mask -- force directory security mode -- force unknown acl user -- inherit permissions -- inherit acls -- inherit owner -- guest only -- only guest -- only user -- allow hosts -- deny hosts -- preload modules -- use kerberos keytab -- syslog -- syslog only -- max log size -- debug timestamp -- timestamp logs -- debug hires timestamp -- debug pid -- debug uid -- allocation roundup size -- aio read size -- aio write size -- aio write behind -- large readwrite -- protocol -- read bmpx -- reset on zero vc -- acl compatibility -- defer sharing violations -- ea support -- nt acl support -- nt pipe support -- profile acls -- map acl inherit -- afs share -- max ttl -- client use spnego -- enable asu support -- svcctl list -- block size -- change notify timeout -- deadtime -- getwd cache -- keepalive -- kernel change notify -- lpq cache time -- max smbd processes -- max disk size -- max open files -- min print space -- strict allocate -- sync always -- use mmap -- use sendfile -- hostname lookups -- write cache size -- name cache timeout -- max reported print jobs -- load printers -- printcap cache time -- printcap name -- printcap -- printing -- cups options -- cups server -- iprint server -- print command -- disable spoolss -- enable spoolss -- lpq command -- lprm command -- lppause command -- lpresume command -- queuepause command -- queueresume command -- enumports command -- addprinter command -- deleteprinter command -- show add printer wizard -- os2 driver map -- use client driver -- default devmode -- force printername -- mangling method -- mangle prefix -- default case -- case sensitive -- casesignames -- preserve case -- short preserve case -- mangling char -- hide dot files -- hide special files -- hide unreadable -- hide unwriteable files -- delete veto files -- veto files -- hide files -- veto oplock files -- map readonly -- mangled names -- mangled map -- max stat cache size -- stat cache -- store dos attributes -- machine password timeout -- add user script -- rename user script -- delete user script -- add group script -- delete group script -- add user to group script -- delete user from group script -- set primary group script -- add machine script -- shutdown script -- abort shutdown script -- username map script -- logon script -- logon path -- logon drive -- logon home -- domain logons -- os level -- lm announce -- lm interval -- domain master -- browse list -- enhanced browsing -- wins proxy -- blocking locks -- fake oplocks -- kernel oplocks -- locking -- lock spin count -- lock spin time -- oplocks -- level2 oplocks -- oplock break wait time -- oplock contention limit -- posix locking -- share modes -- add share command -- change share command -- delete share command -- eventlog list -- utmp directory -- wtmp directory -- utmp -- default service -- default -- message command -- dfree cache time -- dfree command -- get quota command -- set quota command -- remote announce -- remote browse sync -- homedir map -- afs username map -- afs token lifetime -- log nt token command -- time offset -- NIS homedir -- preexec -- exec -- preexec close -- postexec -- root preexec -- root preexec close -- root postexec -- set directory -- wide links -- follow symlinks -- dont descend -- magic script -- magic output -- delete readonly -- dos filemode -- dos filetimes -- dos filetime resolution -- fake directory create times -- panic action -- vfs objects -- vfs object -- msdfs root -- msdfs proxy -- host msdfs -- enable rid algorithm -- passdb expand explicit -- idmap backend -- idmap uid -- winbind uid -- idmap gid -- winbind gid -- template homedir -- template shell -- winbind separator -- winbind cache time -- winbind enum users -- winbind enum groups -- winbind use default domain -- winbind trusted domains only -- winbind nested groups -- winbind max idle children -- winbind nss info - diff --git a/TODO4 b/TODO4 new file mode 100644 index 00000000000..14df8a507a0 --- /dev/null +++ b/TODO4 @@ -0,0 +1,278 @@ +source/build/smb_build/TODO +source/lib/registry/TODO +source/lib/tdr/TODO +source/pidl/TODO + +- seperate adminlog mechanism (as opposed to the current DEBUG log, + which is not really aimed at administrators but more at developers) + Perhaps similar to eventlog so we can also use eventlog to retrieve the data? + +- testsuite for the 'net' tool + +- and a lot of other stuff + +Configuration options +===================== + +The following options don't exist in Samba4 yet +or are not converted by the upgrade script +or will be removed: + +- update encrypted +- public +- guest ok +- client schannel +- server schannel +- allow trusted domains +- hosts equiv +- map to guest +- algorithmic rid base +- root directory +- root dir +- root +- guest account +- enable privileges +- pam password change +- passwd program +- passwd chat debug +- passwd chat timeout +- check password script +- username map +- username level +- unix password sync +- restrict anonymous +- username +- user +- users +- invalid users +- valid users +- admin users +- read list +- write list +- printer admin +- force user +- force group +- group +- write ok +- writeable +- writable +- acl check permissions +- acl group control +- acl map full control +- create mask +- create mode +- force create mode +- security mask +- force security mode +- directory mask +- directory mode +- force directory mode +- directory security mask +- force directory security mode +- force unknown acl user +- inherit permissions +- inherit acls +- inherit owner +- guest only +- only guest +- only user +- allow hosts +- deny hosts +- preload modules +- use kerberos keytab +- syslog +- syslog only +- max log size +- debug timestamp +- timestamp logs +- debug hires timestamp +- debug pid +- debug uid +- allocation roundup size +- aio read size +- aio write size +- aio write behind +- large readwrite +- protocol +- read bmpx +- reset on zero vc +- acl compatibility +- defer sharing violations +- ea support +- nt acl support +- nt pipe support +- profile acls +- map acl inherit +- afs share +- max ttl +- client use spnego +- enable asu support +- svcctl list +- block size +- change notify timeout +- deadtime +- getwd cache +- keepalive +- kernel change notify +- lpq cache time +- max smbd processes +- max disk size +- max open files +- min print space +- strict allocate +- sync always +- use mmap +- use sendfile +- hostname lookups +- write cache size +- name cache timeout +- max reported print jobs +- load printers +- printcap cache time +- printcap name +- printcap +- printing +- cups options +- cups server +- iprint server +- print command +- disable spoolss +- enable spoolss +- lpq command +- lprm command +- lppause command +- lpresume command +- queuepause command +- queueresume command +- enumports command +- addprinter command +- deleteprinter command +- show add printer wizard +- os2 driver map +- use client driver +- default devmode +- force printername +- mangling method +- mangle prefix +- default case +- case sensitive +- casesignames +- preserve case +- short preserve case +- mangling char +- hide dot files +- hide special files +- hide unreadable +- hide unwriteable files +- delete veto files +- veto files +- hide files +- veto oplock files +- map readonly +- mangled names +- mangled map +- max stat cache size +- stat cache +- store dos attributes +- machine password timeout +- add user script +- rename user script +- delete user script +- add group script +- delete group script +- add user to group script +- delete user from group script +- set primary group script +- add machine script +- shutdown script +- abort shutdown script +- username map script +- logon script +- logon path +- logon drive +- logon home +- domain logons +- os level +- lm announce +- lm interval +- domain master +- browse list +- enhanced browsing +- wins proxy +- blocking locks +- fake oplocks +- kernel oplocks +- locking +- lock spin count +- lock spin time +- oplocks +- level2 oplocks +- oplock break wait time +- oplock contention limit +- posix locking +- share modes +- add share command +- change share command +- delete share command +- eventlog list +- utmp directory +- wtmp directory +- utmp +- default service +- default +- message command +- dfree cache time +- dfree command +- get quota command +- set quota command +- remote announce +- remote browse sync +- homedir map +- afs username map +- afs token lifetime +- log nt token command +- time offset +- NIS homedir +- preexec +- exec +- preexec close +- postexec +- root preexec +- root preexec close +- root postexec +- set directory +- wide links +- follow symlinks +- dont descend +- magic script +- magic output +- delete readonly +- dos filemode +- dos filetimes +- dos filetime resolution +- fake directory create times +- panic action +- vfs objects +- vfs object +- msdfs root +- msdfs proxy +- host msdfs +- enable rid algorithm +- passdb expand explicit +- idmap backend +- idmap uid +- winbind uid +- idmap gid +- winbind gid +- template homedir +- template shell +- winbind separator +- winbind cache time +- winbind enum users +- winbind enum groups +- winbind use default domain +- winbind trusted domains only +- winbind nested groups +- winbind max idle children +- winbind nss info + diff --git a/WHATSNEW.txt b/WHATSNEW.txt deleted file mode 100644 index 726fb1cd971..00000000000 --- a/WHATSNEW.txt +++ /dev/null @@ -1,146 +0,0 @@ -What's new in Samba 4 alpha5 -============================ - -Samba 4 is the ambitious next version of the Samba suite that is being -developed in parallel to the stable 3.0 series. The main emphasis in -this branch is support for the Active Directory logon protocols used -by Windows 2000 and above. - -Samba4 alpha5 follows on from the alpha release series we have been -publishing since September 2007 - -WARNINGS -======== - -Samba4 alpha5 is not a final Samba release. That is more a reference -to Samba4's lack of the features we expect you will need than a -statement of code quality, but clearly it hasn't seen a broad -deployment yet. If you were to upgrade Samba3 (or indeed Windows) to -Samba4, you would find many things work, but that other key features -you may have relied on simply are not there yet. - -For example, while Samba 3.0 is an excellent member of a Active -Directory domain, Samba4 is happier as a domain controller, and it is -in this role where it has seen deployment into production. - -Samba4 is subjected to an awesome battery of tests on an -automated basis, we have found Samba4 to be very stable in it's -behaviour. We have to recommend against upgrading production servers -from Samba 3 to Samba 4 at this stage, because there may be the features on -which you may rely that are not present, or the mapping of -your configuration and user database may not be complete. - -If you are upgrading, or looking to develop, test or deploy Samba4, you should -backup all configuration and data. - -NEW FEATURES -============ - -Samba4 supports the server-side of the Active Directory logon environment -used by Windows 2000 and later, so we can do full domain join -and domain logon operations with these clients. - -Our Domain Controller (DC) implementation includes our own built-in -LDAP server and Kerberos Key Distribution Center (KDC) as well as the -Samba3-like logon services provided over CIFS. We correctly generate -the infamous Kerberos PAC, and include it with the Kerberos tickets we -issue. - -The new VFS features in Samba 4 adapts the filesystem on the server to -match the Windows client semantics, allowing Samba 4 to better match -windows behaviour and application expectations. This includes file -annotation information (in streams) and NT ACLs in particular. The -VFS is backed with an extensive automated test suite. - -A new scripting interface has been added to Samba 4, allowing -Python programs to interface to Samba's internals. - -The Samba 4 architecture is based around an LDAP-like database that -can use a range of modular backends. One of the backends supports -standards compliant LDAP servers (including OpenLDAP), and we are -working on modules to map between AD-like behaviours and this backend. -We are aiming for Samba 4 to be powerful frontend to large -directories. - -CHANGES SINCE Alpha4 -===================== - -In the time since Samba4 Alpha4 was released in June 2008, Samba has -continued to evolve, but you may particularly notice these areas: - - LDAP backend support restored (issues preventing the use of the LDAP - backend in alpha4 have been addressed). - - SMB2 Support: The SMB2 server, while still disabled, has improved, - and now supports SMB2 signing. - - OpenChange support: Updates have been made since alpha4 to better - support OpenChange's use of Samba4's libraries. - - Faster ldb loading: A fix to avoid calling 'init_module' (which was - not defined by Samba modules, but was by the C library) will fix - some of the slowness in authentication. - - SWAT Remains Disabled: Due to a lack of developer time and without a - long-term web developer to maintain it, the SWAT web UI remains been - disabled (and would need to be rewritten in python in any case). - - GNU Make: To try and simplfy our build system, we rely on GNU Make - to avoid autogenerating a massive single makefile. - - -These are just some of the highlights of the work done in the past few -months. More details can be found in our GIT history. - - -CHANGES -======= - -Those familiar with Samba 3 can find a list of user-visible changes -since that release series in the NEWS file. - -KNOWN ISSUES -============ - -- Domain member support is in it's infancy, and is not comparable to - the support found in Samba3. - -- There is no printing support in the current release. - -- There is no NetBIOS browsing support in the current release - -- The Samba4 port of the CTDB clustering support is not yet complete - -- Clock Synchronisation is critical. Many 'wrong password' errors are - actually due to Kerberos objecting to a clock skew between client - and server. (The NTP work in the previous alpha is partly to assist - with this problem). - -- Samba4 alpha5 is currently only portable to recent Linux - distributions. Work to return support for other Unix varients is - expected during the next alpha cycle - -- Samba4 alpha5 is incompatible with GnuTLS 2.0, found in Fedora 9 and - recent Ubuntu releases. GnuTLS use may be disabled using the - --disable-gnutls argument to ./configure. (otherwise 'make test' and - LDAPS operations will hang). - -RUNNING Samba4 -============== - -A short guide to setting up Samba 4 can be found in the howto.txt file -in root of the tarball. - -DEVELOPMENT and FEEDBACK -======================== -Bugs can be filed at https://bugzilla.samba.org/ but please be aware -that many features are simply not expected to work at this stage. - -The Samba Wiki at http://wiki.samba.org should detail some of these -development plans. - -Development and general discussion about Samba 4 happens mainly on -the #samba-technical IRC channel (on irc.freenode.net) and -the samba-technical mailing list (see http://lists.samba.org/ for -details). - diff --git a/WHATSNEW4.txt b/WHATSNEW4.txt new file mode 100644 index 00000000000..726fb1cd971 --- /dev/null +++ b/WHATSNEW4.txt @@ -0,0 +1,146 @@ +What's new in Samba 4 alpha5 +============================ + +Samba 4 is the ambitious next version of the Samba suite that is being +developed in parallel to the stable 3.0 series. The main emphasis in +this branch is support for the Active Directory logon protocols used +by Windows 2000 and above. + +Samba4 alpha5 follows on from the alpha release series we have been +publishing since September 2007 + +WARNINGS +======== + +Samba4 alpha5 is not a final Samba release. That is more a reference +to Samba4's lack of the features we expect you will need than a +statement of code quality, but clearly it hasn't seen a broad +deployment yet. If you were to upgrade Samba3 (or indeed Windows) to +Samba4, you would find many things work, but that other key features +you may have relied on simply are not there yet. + +For example, while Samba 3.0 is an excellent member of a Active +Directory domain, Samba4 is happier as a domain controller, and it is +in this role where it has seen deployment into production. + +Samba4 is subjected to an awesome battery of tests on an +automated basis, we have found Samba4 to be very stable in it's +behaviour. We have to recommend against upgrading production servers +from Samba 3 to Samba 4 at this stage, because there may be the features on +which you may rely that are not present, or the mapping of +your configuration and user database may not be complete. + +If you are upgrading, or looking to develop, test or deploy Samba4, you should +backup all configuration and data. + +NEW FEATURES +============ + +Samba4 supports the server-side of the Active Directory logon environment +used by Windows 2000 and later, so we can do full domain join +and domain logon operations with these clients. + +Our Domain Controller (DC) implementation includes our own built-in +LDAP server and Kerberos Key Distribution Center (KDC) as well as the +Samba3-like logon services provided over CIFS. We correctly generate +the infamous Kerberos PAC, and include it with the Kerberos tickets we +issue. + +The new VFS features in Samba 4 adapts the filesystem on the server to +match the Windows client semantics, allowing Samba 4 to better match +windows behaviour and application expectations. This includes file +annotation information (in streams) and NT ACLs in particular. The +VFS is backed with an extensive automated test suite. + +A new scripting interface has been added to Samba 4, allowing +Python programs to interface to Samba's internals. + +The Samba 4 architecture is based around an LDAP-like database that +can use a range of modular backends. One of the backends supports +standards compliant LDAP servers (including OpenLDAP), and we are +working on modules to map between AD-like behaviours and this backend. +We are aiming for Samba 4 to be powerful frontend to large +directories. + +CHANGES SINCE Alpha4 +===================== + +In the time since Samba4 Alpha4 was released in June 2008, Samba has +continued to evolve, but you may particularly notice these areas: + + LDAP backend support restored (issues preventing the use of the LDAP + backend in alpha4 have been addressed). + + SMB2 Support: The SMB2 server, while still disabled, has improved, + and now supports SMB2 signing. + + OpenChange support: Updates have been made since alpha4 to better + support OpenChange's use of Samba4's libraries. + + Faster ldb loading: A fix to avoid calling 'init_module' (which was + not defined by Samba modules, but was by the C library) will fix + some of the slowness in authentication. + + SWAT Remains Disabled: Due to a lack of developer time and without a + long-term web developer to maintain it, the SWAT web UI remains been + disabled (and would need to be rewritten in python in any case). + + GNU Make: To try and simplfy our build system, we rely on GNU Make + to avoid autogenerating a massive single makefile. + + +These are just some of the highlights of the work done in the past few +months. More details can be found in our GIT history. + + +CHANGES +======= + +Those familiar with Samba 3 can find a list of user-visible changes +since that release series in the NEWS file. + +KNOWN ISSUES +============ + +- Domain member support is in it's infancy, and is not comparable to + the support found in Samba3. + +- There is no printing support in the current release. + +- There is no NetBIOS browsing support in the current release + +- The Samba4 port of the CTDB clustering support is not yet complete + +- Clock Synchronisation is critical. Many 'wrong password' errors are + actually due to Kerberos objecting to a clock skew between client + and server. (The NTP work in the previous alpha is partly to assist + with this problem). + +- Samba4 alpha5 is currently only portable to recent Linux + distributions. Work to return support for other Unix varients is + expected during the next alpha cycle + +- Samba4 alpha5 is incompatible with GnuTLS 2.0, found in Fedora 9 and + recent Ubuntu releases. GnuTLS use may be disabled using the + --disable-gnutls argument to ./configure. (otherwise 'make test' and + LDAPS operations will hang). + +RUNNING Samba4 +============== + +A short guide to setting up Samba 4 can be found in the howto.txt file +in root of the tarball. + +DEVELOPMENT and FEEDBACK +======================== +Bugs can be filed at https://bugzilla.samba.org/ but please be aware +that many features are simply not expected to work at this stage. + +The Samba Wiki at http://wiki.samba.org should detail some of these +development plans. + +Development and general discussion about Samba 4 happens mainly on +the #samba-technical IRC channel (on irc.freenode.net) and +the samba-technical mailing list (see http://lists.samba.org/ for +details). + diff --git a/howto.txt b/howto.txt deleted file mode 100644 index 3ae225ddb87..00000000000 --- a/howto.txt +++ /dev/null @@ -1,188 +0,0 @@ -Samba4 developer howto -====================== - -tridge@samba.org, December 2004 - -A more up to date version of this howto can be found in the wiki -at http://wiki.samba.org/index.php/Samba4/HOWTO. - -This is a very basic document on how to setup a simple Samba4 -server. This is aimed at developers who are already familiar with -Samba3 and wish to participate in Samba4 development. This is not -aimed at production use of Samba4. - -.. contents:: - -Step 1: download Samba4 ------------------------ - -If you have downloaded the Samba4 code via a tarball released from the -samba.org website, Step 1 has already been completed for you. For testing -with the version released in the tarball, you may continue on to Step 2. Note -that the references below to the top-level directory named "samba4" will -instead be based on the name of the tarball downloaded (e.g. -"samba-4.0.0alpha3" for the tarball samba-4.0.0alpha3.tar.gz). - -There are 2 methods of doing this: - - method 1: "rsync -avz samba.org::ftp/unpacked/samba_4_0_test/ samba4" - - method 2: "git clone git://git.samba.org/samba.git samba4; cd samba4 && git checkout -b v4-0-test origin/v4-0-test; cd .." - -both methods will create a directory called "samba4" in the current -directory. If you don't have rsync or git then install one of them. - -Since only released versions of Samba contain a pregenerated configure script, -you will have to generate it by hand:: - - $ cd samba4/source - $ ./autogen.sh - -Note that the above rsync command will give you a checked out git -repository. So if you also have git you can update it to the latest -version at some future date using:: - - $ cd samba4 - $ git pull origin v4-0-test - -Step 2: compile Samba4 ----------------------- - -Recommended optional development libraries: -- acl and xattr development libraries -- gnutls -- readline - -Run this:: - - $ cd samba4/source - $ ./configure - $ make - -Step 3: install Samba4 ----------------------- - -Run this as a user who have permission to write to the install -directory (defaults to /usr/local/samba). Use --prefix option to -configure above to change this. - -:: - - # make install - - -Step 4: provision Samba4 ------------------------- - -The "provision" step sets up a basic user database. -Must be run as a user with permission to write to the install directory. - -:: - - # cd source - # ./setup/provision --realm=YOUR.REALM --domain=YOURDOM \ - # --adminpass=SOMEPASSWORD --server-role='domain controller' - -'YOURDOM' is the NT4 style domain name. 'YOUR.REALM' is your kerberos -realm, which is typically your DNS domain name. - -Step 5: Create a simple smb.conf --------------------------------- - -The provisioning will create a very simple smb.conf with no shares by -default. You will need to update it to add at least one share. For -example:: - - [test] - path = /data/test - read only = no - - -Step 6: starting Samba4 ------------------------ - -The simplest is to just run "smbd", but as a developer you may find -the following more useful:: - - # smbd -i -M single - -that means "start smbd without messages in stdout, and running a -single process. That mode of operation makes debugging smbd with gdb -particularly easy. - -Note that now it is no longer necessary to have an instance of nmbd -from Samba 3 running. If you are running any smbd or nmbd processes -they need to be stopped before starting smbd from Samba 4. - -Make sure you put the bin and sbin directories from your new install -in your $PATH. Make sure you run the right version! - - -Step 7: testing Samba4 ----------------------- - -try this command:: - - $ smbclient //localhost/test -Uadministrator%SOMEPASSWORD - - -NOTE about filesystem support ------------------------------ - -To use the advanced features of Samba4 you need a filesystem that -supports both the "user" and "system" xattr namespaces. - -If you run Linux with a 2.6 kernel and ext3 this means you need to -include the option "user_xattr" in your /etc/fstab. For example:: - - /dev/hda3 /home ext3 user_xattr 1 1 - -You also need to compile your kernel with the XATTR and SECURITY -options for your filesystem. For ext3 that means you need:: - - CONFIG_EXT3_FS_XATTR=y - CONFIG_EXT3_FS_SECURITY=y - -If you are running a Linux 2.6 kernel with CONFIG_IKCONFIG_PROC -defined you can check this with the following command:: - - $ zgrep CONFIG_EXT3_FS /proc/config.gz - -If you don't have a filesystem with xattr support, then you can -simulate it by using the option:: - - posix:eadb = /usr/local/samba/eadb.tdb - -that will place all extra file attributes (NT ACLs, DOS EAs, streams -etc), in that tdb. It is not efficient, and doesn't scale well, but at -least it gives you a choice when you don't have a modern filesystem. - -Testing your filesystem ------------------------ - -To test your filesystem support, install the 'attr' package and run -the following 4 commands as root:: - - # touch test.txt - # setfattr -n user.test -v test test.txt - # setfattr -n security.test -v test2 test.txt - # getfattr -d test.txt - # getfattr -n security.test -d test.txt - -You should see output like this:: - - # file: test.txt - user.test="test" - - # file: test.txt - security.test="test2" - -If you get any "Operation not supported" errors then it means your -kernel is not configured correctly, or your filesystem is not mounted -with the right options. - -If you get any "Operation not permitted" errors then it probably means -you didn't try the test as root. - -.. - vim: ft=rest diff --git a/howto4.txt b/howto4.txt new file mode 100644 index 00000000000..3ae225ddb87 --- /dev/null +++ b/howto4.txt @@ -0,0 +1,188 @@ +Samba4 developer howto +====================== + +tridge@samba.org, December 2004 + +A more up to date version of this howto can be found in the wiki +at http://wiki.samba.org/index.php/Samba4/HOWTO. + +This is a very basic document on how to setup a simple Samba4 +server. This is aimed at developers who are already familiar with +Samba3 and wish to participate in Samba4 development. This is not +aimed at production use of Samba4. + +.. contents:: + +Step 1: download Samba4 +----------------------- + +If you have downloaded the Samba4 code via a tarball released from the +samba.org website, Step 1 has already been completed for you. For testing +with the version released in the tarball, you may continue on to Step 2. Note +that the references below to the top-level directory named "samba4" will +instead be based on the name of the tarball downloaded (e.g. +"samba-4.0.0alpha3" for the tarball samba-4.0.0alpha3.tar.gz). + +There are 2 methods of doing this: + + method 1: "rsync -avz samba.org::ftp/unpacked/samba_4_0_test/ samba4" + + method 2: "git clone git://git.samba.org/samba.git samba4; cd samba4 && git checkout -b v4-0-test origin/v4-0-test; cd .." + +both methods will create a directory called "samba4" in the current +directory. If you don't have rsync or git then install one of them. + +Since only released versions of Samba contain a pregenerated configure script, +you will have to generate it by hand:: + + $ cd samba4/source + $ ./autogen.sh + +Note that the above rsync command will give you a checked out git +repository. So if you also have git you can update it to the latest +version at some future date using:: + + $ cd samba4 + $ git pull origin v4-0-test + +Step 2: compile Samba4 +---------------------- + +Recommended optional development libraries: +- acl and xattr development libraries +- gnutls +- readline + +Run this:: + + $ cd samba4/source + $ ./configure + $ make + +Step 3: install Samba4 +---------------------- + +Run this as a user who have permission to write to the install +directory (defaults to /usr/local/samba). Use --prefix option to +configure above to change this. + +:: + + # make install + + +Step 4: provision Samba4 +------------------------ + +The "provision" step sets up a basic user database. +Must be run as a user with permission to write to the install directory. + +:: + + # cd source + # ./setup/provision --realm=YOUR.REALM --domain=YOURDOM \ + # --adminpass=SOMEPASSWORD --server-role='domain controller' + +'YOURDOM' is the NT4 style domain name. 'YOUR.REALM' is your kerberos +realm, which is typically your DNS domain name. + +Step 5: Create a simple smb.conf +-------------------------------- + +The provisioning will create a very simple smb.conf with no shares by +default. You will need to update it to add at least one share. For +example:: + + [test] + path = /data/test + read only = no + + +Step 6: starting Samba4 +----------------------- + +The simplest is to just run "smbd", but as a developer you may find +the following more useful:: + + # smbd -i -M single + +that means "start smbd without messages in stdout, and running a +single process. That mode of operation makes debugging smbd with gdb +particularly easy. + +Note that now it is no longer necessary to have an instance of nmbd +from Samba 3 running. If you are running any smbd or nmbd processes +they need to be stopped before starting smbd from Samba 4. + +Make sure you put the bin and sbin directories from your new install +in your $PATH. Make sure you run the right version! + + +Step 7: testing Samba4 +---------------------- + +try this command:: + + $ smbclient //localhost/test -Uadministrator%SOMEPASSWORD + + +NOTE about filesystem support +----------------------------- + +To use the advanced features of Samba4 you need a filesystem that +supports both the "user" and "system" xattr namespaces. + +If you run Linux with a 2.6 kernel and ext3 this means you need to +include the option "user_xattr" in your /etc/fstab. For example:: + + /dev/hda3 /home ext3 user_xattr 1 1 + +You also need to compile your kernel with the XATTR and SECURITY +options for your filesystem. For ext3 that means you need:: + + CONFIG_EXT3_FS_XATTR=y + CONFIG_EXT3_FS_SECURITY=y + +If you are running a Linux 2.6 kernel with CONFIG_IKCONFIG_PROC +defined you can check this with the following command:: + + $ zgrep CONFIG_EXT3_FS /proc/config.gz + +If you don't have a filesystem with xattr support, then you can +simulate it by using the option:: + + posix:eadb = /usr/local/samba/eadb.tdb + +that will place all extra file attributes (NT ACLs, DOS EAs, streams +etc), in that tdb. It is not efficient, and doesn't scale well, but at +least it gives you a choice when you don't have a modern filesystem. + +Testing your filesystem +----------------------- + +To test your filesystem support, install the 'attr' package and run +the following 4 commands as root:: + + # touch test.txt + # setfattr -n user.test -v test test.txt + # setfattr -n security.test -v test2 test.txt + # getfattr -d test.txt + # getfattr -n security.test -d test.txt + +You should see output like this:: + + # file: test.txt + user.test="test" + + # file: test.txt + security.test="test2" + +If you get any "Operation not supported" errors then it means your +kernel is not configured correctly, or your filesystem is not mounted +with the right options. + +If you get any "Operation not permitted" errors then it probably means +you didn't try the test as root. + +.. + vim: ft=rest diff --git a/prog_guide.txt b/prog_guide.txt deleted file mode 100644 index bba58b31b3b..00000000000 --- a/prog_guide.txt +++ /dev/null @@ -1,789 +0,0 @@ - - -THIS IS INCOMPLETE! I'M ONLY COMMITING IT IN ORDER TO SOLICIT COMMENTS -FROM A FEW PEOPLE. DON'T TAKE THIS AS THE FINAL VERSION YET. - - -Samba4 Programming Guide ------------------------- - -The internals of Samba4 are quite different from previous versions of -Samba, so even if you are an experienced Samba developer please take -the time to read through this document. - -This document will explain both the broad structure of Samba4, and -some of the common coding elements such as memory management and -dealing with macros. - - -Coding Style ------------- - -In past versions of Samba we have basically let each programmer choose -their own programming style. Unfortunately the result has often been -that code that other members of the team find difficult to read. For -Samba version 4 I would like to standardise on a common coding style -to make the whole tree more readable. For those of you who are -horrified at the idea of having to learn a new style, I can assure you -that it isn't as painful as you might think. I was forced to adopt a -new style when I started working on the Linux kernel, and after some -initial pain found it quite easy. - -That said, I don't want to invent a new style, instead I would like to -adopt the style used by the Linux kernel. It is a widely used style -with plenty of support tools available. See Documentation/CodingStyle -in the Linux source tree. This is the style that I have used to write -all of the core infrastructure for Samba4 and I think that we should -continue with that style. - -I also think that we should most definately *not* adopt an automatic -reformatting system in cvs (or whatever other source code system we -end up using in the future). Such automatic formatters are, in my -experience, incredibly error prone and don't understand the necessary -exceptions. I don't mind if people use automated tools to reformat -their own code before they commit it, but please do not run such -automated tools on large slabs of existing code without being willing -to spend a *lot* of time hand checking the results. - -Finally, I think that for code that is parsing or formatting protocol -packets the code layout should strongly reflect the packet -format. That means ordring the code so that it parses in the same -order as the packet is stored on the wire (where possible) and using -white space to align packet offsets so that a reader can immediately -map any line of the code to the corresponding place in the packet. - - -Static and Global Data ----------------------- - -The basic rule is "avoid static and global data like the plague". What -do I mean by static data? The way to tell if you have static data in a -file is to use the "size" utility in Linux. For example if we run:: - - size libcli/raw/*.o - -in Samba4 then you get the following:: - - text data bss dec hex filename - 2015 0 0 2015 7df libcli/raw/clikrb5.o - 202 0 0 202 ca libcli/raw/clioplock.o - 35 0 0 35 23 libcli/raw/clirewrite.o - 3891 0 0 3891 f33 libcli/raw/clisession.o - 869 0 0 869 365 libcli/raw/clisocket.o - 4962 0 0 4962 1362 libcli/raw/clispnego.o - 1223 0 0 1223 4c7 libcli/raw/clitransport.o - 2294 0 0 2294 8f6 libcli/raw/clitree.o - 1081 0 0 1081 439 libcli/raw/raweas.o - 6765 0 0 6765 1a6d libcli/raw/rawfile.o - 6824 0 0 6824 1aa8 libcli/raw/rawfileinfo.o - 2944 0 0 2944 b80 libcli/raw/rawfsinfo.o - 541 0 0 541 21d libcli/raw/rawioctl.o - 1728 0 0 1728 6c0 libcli/raw/rawnegotiate.o - 723 0 0 723 2d3 libcli/raw/rawnotify.o - 3779 0 0 3779 ec3 libcli/raw/rawreadwrite.o - 6597 0 0 6597 19c5 libcli/raw/rawrequest.o - 5580 0 0 5580 15cc libcli/raw/rawsearch.o - 3034 0 0 3034 bda libcli/raw/rawsetfileinfo.o - 5187 0 0 5187 1443 libcli/raw/rawtrans.o - 2033 0 0 2033 7f1 libcli/raw/smb_signing.o - -notice that the "data" and "bss" columns are all zero? That is -good. If there are any non-zero values in data or bss then that -indicates static data and is bad (as a rule of thumb). - -Lets compare that result to the equivalent in Samba3:: - - text data bss dec hex filename - 3978 0 0 3978 f8a libsmb/asn1.o - 18963 0 288 19251 4b33 libsmb/cliconnect.o - 2815 0 1024 3839 eff libsmb/clidgram.o - 4038 0 0 4038 fc6 libsmb/clientgen.o - 3337 664 256 4257 10a1 libsmb/clierror.o - 10043 0 0 10043 273b libsmb/clifile.o - 332 0 0 332 14c libsmb/clifsinfo.o - 166 0 0 166 a6 libsmb/clikrb5.o - 5212 0 0 5212 145c libsmb/clilist.o - 1367 0 0 1367 557 libsmb/climessage.o - 259 0 0 259 103 libsmb/clioplock.o - 1584 0 0 1584 630 libsmb/cliprint.o - 7565 0 256 7821 1e8d libsmb/cliquota.o - 7694 0 0 7694 1e0e libsmb/clirap.o - 27440 0 0 27440 6b30 libsmb/clirap2.o - 2905 0 0 2905 b59 libsmb/clireadwrite.o - 1698 0 0 1698 6a2 libsmb/clisecdesc.o - 5517 0 0 5517 158d libsmb/clispnego.o - 485 0 0 485 1e5 libsmb/clistr.o - 8449 0 0 8449 2101 libsmb/clitrans.o - 2053 0 4 2057 809 libsmb/conncache.o - 3041 0 256 3297 ce1 libsmb/credentials.o - 1261 0 1024 2285 8ed libsmb/doserr.o - 14560 0 0 14560 38e0 libsmb/errormap.o - 3645 0 0 3645 e3d libsmb/namecache.o - 16815 0 8 16823 41b7 libsmb/namequery.o - 1626 0 0 1626 65a libsmb/namequery_dc.o - 14301 0 1076 15377 3c11 libsmb/nmblib.o - 24516 0 2048 26564 67c4 libsmb/nterr.o - 8661 0 8 8669 21dd libsmb/ntlmssp.o - 3188 0 0 3188 c74 libsmb/ntlmssp_parse.o - 4945 0 0 4945 1351 libsmb/ntlmssp_sign.o - 1303 0 0 1303 517 libsmb/passchange.o - 1221 0 0 1221 4c5 libsmb/pwd_cache.o - 2475 0 4 2479 9af libsmb/samlogon_cache.o - 10768 32 0 10800 2a30 libsmb/smb_signing.o - 4524 0 16 4540 11bc libsmb/smbdes.o - 5708 0 0 5708 164c libsmb/smbencrypt.o - 7049 0 3072 10121 2789 libsmb/smberr.o - 2995 0 0 2995 bb3 libsmb/spnego.o - 3186 0 0 3186 c72 libsmb/trustdom_cache.o - 1742 0 0 1742 6ce libsmb/trusts_util.o - 918 0 28 946 3b2 libsmb/unexpected.o - -notice all of the non-zero data and bss elements? Every bit of that -data is a bug waiting to happen. - -Static data is evil as it has the following consequences: -- it makes code much less likely to be thread-safe -- it makes code much less likely to be recursion-safe -- it leads to subtle side effects when the same code is called from - multiple places -- doesn't play well with shared libraries or plugins - -Static data is particularly evil in library code (such as our internal -smb and rpc libraries). If you can get rid of all static data in -libraries then you can make some fairly strong guarantees about the -behaviour of functions in that library, which really helps. - -Of course, it is possible to write code that uses static data and is -safe, it's just much harder to do that than just avoid static data in -the first place. We have been tripped up countless times by subtle -bugs in Samba due to the use of static data, so I think it is time to -start avoiding it in new code. Much of the core infrastructure of -Samba4 was specifically written to avoid static data, so I'm going to -be really annoyed if everyone starts adding lots of static data back -in. - -So, how do we avoid static data? The basic method is to use context -pointers. When reading the Samba4 code you will notice that just about -every function takes a pointer to a context structure as its first -argument. Any data that the function needs that isn't an explicit -argument to the function can be found by traversing that context. - -Note that this includes all of the little caches that we have lying -all over the code in Samba3. I'm referring to the ones that generally -have a "static int initialised" and then some static string or integer -that remembers the last return value of the function. Get rid of them! -If you are *REALLY* absolutely completely certain that your personal -favourite mini-cache is needed then you should do it properly by -putting it into the appropriate context rather than doing it the lazy -way by putting it inside the target function. I would suggest however -that the vast majority of those little caches are useless - don't -stick it in unless you have really firm benchmarking results that show -that it is needed and helps by a significant amount. - -Note that Samba4 is not yet completely clean of static data like -this. I've gotten the smbd/ directory down to 24 bytes of static data, -and libcli/raw/ down to zero. I've also gotten the ntvfs layer and all -backends down to just 8 bytes in ntvfs_base.c. The rest still needs -some more work. - -Also note that truly constant data is OK, and will not in fact show up -in the data and bss columns in "size" anyway (it will be included in -"text"). So you can have constant tables of protocol data. - - -How to use talloc ------------------ - -Please see the separate document, source/lib/talloc/talloc_guide.txt -You _must_ read this if you want to program in Samba4. - - -Interface Structures --------------------- - -One of the biggest changes in Samba4 is the universal use of interface -structures. Go take a look through include/smb_interfaces.h now to get -an idea of what I am talking about. - -In Samba3 many of the core wire structures in the SMB protocol were -never explicitly defined in Samba. Instead, our parse and generation -functions just worked directly with wire buffers. The biggest problem -with this is that is tied our parse code with our "business logic" -much too closely, which meant the code got extremely confusing to -read. - -In Samba4 we have explicitly defined interface structures for -everything in the protocol. When we receive a buffer we always parse -it completely into one of these structures, then we pass a pointer to -that structure to a backend handler. What we must *not* do is make any -decisions about the data inside the parse functions. That is critical -as different backends will need different portions of the data. This -leads to a golden rule for Samba4: - - "don't design interfaces that lose information" - -In Samba3 our backends often received "condensed" versions of the -information sent from clients, but this inevitably meant that some -backends could not get at the data they needed to do what they wanted, -so from now on we should expose the backends to all of the available -information and let them choose which bits they want. - -Ok, so now some of you will be thinking "this sounds just like our -msrpc code from Samba3", and while to some extent this is true there -are extremely important differences in the approach that are worth -pointing out. - -In the Samba3 msrpc code we used explicit parse structures for all -msrpc functions. The problem is that we didn't just put all of the -real variables in these structures, we also put in all the artifacts -as well. A good example is the security descriptor strucrure that -looks like this in Samba3:: - - typedef struct security_descriptor_info - { - uint16 revision; - uint16 type; - - uint32 off_owner_sid; - uint32 off_grp_sid; - uint32 off_sacl; - uint32 off_dacl; - - SEC_ACL *dacl; - SEC_ACL *sacl; - DOM_SID *owner_sid; - DOM_SID *grp_sid; - } SEC_DESC; - -The problem with this structure is all the off_* variables. Those are -not part of the interface, and do not appear in any real descriptions -of Microsoft security descriptors. They are parsing artifacts -generated by the IDL compiler that Microsoft use. That doesn't mean -they aren't needed on the wire - indeed they are as they tell the -parser where to find the following four variables, but they should -*NOT* be in the interface structure. - -In Samba3 there were unwritten rules about which variables in a -structure a high level caller has to fill in and which ones are filled -in by the marshalling code. In Samba4 those rules are gone, because -the redundent artifact variables are gone. The high level caller just -sets up the real variables and the marshalling code worries about -generating the right offsets. - -The same rule applies to strings. In many places in the SMB and MSRPC -protocols complex strings are used on the wire, with complex rules -about padding, format, alighment, termination etc. None of that -information is useful to a high level calling routine or to a backend -- its all just so much wire fluff. So, in Samba4 these strings are -just "char *" and are always in our internal multi-byte format (which -is usually UTF8). It is up to the parse functions to worry about -translating the format and getting the padding right. - -The one exception to this is the use of the WIRE_STRING type, but that -has a very good justification in terms of regression testing. Go and -read the comment in smb_interfaces.h about that now. - -So, here is another rule to code by. When writing an interface -structure think carefully about what variables in the structure can be -left out as they are redundent. If some length is effectively defined -twice on the wire then only put it once in the packet. If a length can -be inferred from a null termination then do that and leave the length -out of the structure completely. Don't put redundent stuff in -structures! - - -Async Design ------------- - -Samba4 has an asynchronous design. That affects *lots* of the code, -and the implications of the asynchronous design needs to be considered -just about everywhere. - -The first aspect of the async design to look at is the SMB client -library. Lets take a look at the following three functions in -libcli/raw/rawfile.c:: - - struct cli_request *smb_raw_seek_send(struct cli_tree *tree, struct smb_seek *parms); - NTSTATUS smb_raw_seek_recv(struct cli_request *req, struct smb_seek *parms); - NTSTATUS smb_raw_seek(struct cli_tree *tree, struct smb_seek *parms); - -Go and read them now then come back. - -Ok, first notice there there are 3 separate functions, whereas the -equivalent code in Samba3 had just one. Also note that the 3rd -function is extremely simple - its just a wrapper around calling the -first two in order. - -The three separate functions are needed because we need to be able to -generate SMB calls asynchronously. The first call, which for smb calls -is always called smb_raw_XXXX_send(), constructs and sends a SMB -request and returns a "struct cli_request" which acts as a handle for -the request. The caller is then free to do lots of other calls if it -wants to, then when it is ready it can call the smb_raw_XXX_recv() -function to receive the reply. - -If all you want is a synchronous call then call the 3rd interface, the -one called smb_raw_XXXX(). That just calls the first two in order, and -blocks waiting for the reply. - -But what if you want to be called when the reply comes in? Yes, thats -possible. You can do things like this:: - - struct cli_request *req; - - req = smb_raw_XXX_send(tree, params); - - req->async.fn = my_callback; - req->async.private = my_private_data; - -then in your callback function you can call the smb_raw_XXXX_recv() -function to receive the reply. Your callback will receive the "req" -pointer, which you can use to retrieve your private data from -req->async.private. - -Then all you need to do is ensure that the main loop in the client -library gets called. You can either do that by polling the connection -using cli_transport_pending() and cli_request_receive_next() or you -can use transport->idle.func to setup an idle function handler to call -back to your main code. Either way, you can build a fully async -application. - -In order to support all of this we have to make sure that when we -write a piece of library code (SMB, MSRPC etc) that we build the -separate _send() and _recv() functions. It really is worth the effort. - -Now about async in smbd, a much more complex topic. - -The SMB protocol is inherently async. Some functions (such as change -notify) often don't return for hours, while hundreds of other -functions pass through the socket. Take a look at the RAW-MUX test in -the Samba4 smbtorture to see some really extreme examples of the sort -of async operations that Windows supports. I particularly like the -open/open/close sequence where the 2nd open (which conflicts with the -first) succeeds because the subsequent close is answered out of order. - -In Samba3 we handled this stuff very badly. We had awful "pending -request" queues that allocated full 128k packet buffers, and even with -all that crap we got the semantics wrong. In Samba4 I intend to make -sure we get this stuff right. - -So, how do we do this? We now have an async interface between smbd and -the NTVFS backends. Whenever smbd calls into a backend the backend has -an option of answer the request in a synchronous fashion if it wants -to just like in Samba3, but it also has the option of answering the -request asynchronously. The only backend that currently does this is -the CIFS backend, but I hope the other backends will soon do this to. - -To make this work you need to do things like this in the backend:: - - req->control_flags |= REQ_CONTROL_ASYNC; - -that tells smbd that the backend has elected to reply later rather -than replying immediately. The backend must *only* do this if -req->async.send_fn is not NULL. If send_fn is NULL then it means that -the smbd front end cannot handle this function being replied to in an -async fashion. - -If the backend does this then it is up to the backend to call -req->async.send_fn() when it is ready to reply. It the meantime smbd -puts the call on hold and goes back to answering other requests on the -socket. - -Inside smbd you will find that there is code to support this. The most -obvious change is that smbd splits each SMB reply function into two -parts - just like the client library has a _send() and _recv() -function, so smbd has a _send() function and the parse function for -each SMB. - -As an example go and have a look at reply_getatr_send() and -reply_getatr() in smb_server/reply.c. Read them? Good. - -Notice that reply_getatr() sets up the req->async structure to contain -the send function. Thats how the backend gets to do an async reply, it -calls this function when it is ready. Also notice that reply_getatr() -only does the parsing of the request, and does not do the reply -generation. That is done by the _send() function. - -The only missing piece in the Samba4 right now that prevents it being -fully async is that it currently does the low level socket calls (read -and write on sockets) in a blocking fashion. It does use select() to -make it somewhat async, but if a client were to send a partial packet -then delay before sending the rest then smbd would be stuck waiting -for the second half of the packet. - -To fix this I plan on making the socket calls async as well, which -luckily will not involve any API changes in the core of smbd or the -library. It just involves a little bit of extra code in clitransport.c -and smbd/request.c. As a side effect I hope that this will also reduce -the average number of system calls required to answer a request, so we -may see a performance improvement. - - -NTVFS ------ - -One of the most noticeable changes in Samba4 is the introduction of -the NTVFS layer. This provided the initial motivation for the design -of Samba4 and in many ways lies at the heart of the design. - -In Samba3 the main file serving process (smbd) combined the handling -of the SMB protocol with the mapping to POSIX semantics in the same -code. If you look in smbd/reply.c in Samba3 you see numerous places -where POSIX assumptions are mixed tightly with SMB parsing code. We -did have a VFS layer in Samba3, but it was a POSIX-like VFS layer, so -no matter how you wrote a plugin you could not bypass the POSIX -mapping decisions that had already been made before the VFS layer was -called. - -In Samba4 things are quite different. All SMB parsing is performed in -the smbd front end, then fully parsed requests are passed to the NTVFS -backend. That backend makes any semantic mapping decisions and fills -in the 'out' portion of the request. The front end is then responsible -for putting those results into wire format and sending them to the -client. - -Lets have a look at one of those request structures. Go and read the -definition of "union smb_write" and "enum write_level" in -include/smb_interfaces.h. (no, don't just skip reading it, really go -and read it. Yes, that means you!). - -Notice the union? That's how Samba4 allows a single NTVFS backend -interface to handle the several different ways of doing a write -operation in the SMB protocol. Now lets look at one section of that -union:: - - /* SMBwriteX interface */ - struct { - enum write_level level; - - struct { - uint16 fnum; - SMB_BIG_UINT offset; - uint16 wmode; - uint16 remaining; - uint32 count; - const char *data; - } in; - struct { - uint32 nwritten; - uint16 remaining; - } out; - } writex; - -see the "in" and "out" sections? The "in" section is for parameters -that the SMB client sends on the wire as part of the request. The smbd -front end parse code parses the wire request and fills in all those -parameters. It then calls the NTVFS interface which looks like this:: - - NTSTATUS (*write)(struct request_context *req, union smb_write *io); - -and the NTVFS backend does the write request. The backend then fills -in the "out" section of the writex structure and gives the union back -to the front end (either by returning, or if done in an async fashion -then by calling the async send function. See the async discussion -elsewhere in this document). - -The NTVFS backend knows which particular function is being requested -by looking at io->generic.level. Notice that this enum is also -repeated inside each of the sub-structures in the union, so the -backend could just as easily look at io->writex.level and would get -the same variable. - -Notice also that some levels (such as splwrite) don't have an "out" -section. This happens because there is no return value apart from a -status code from those SMB calls. - -So what about status codes? The status code is returned directly by -the backend NTVFS interface when the call is performed -synchronously. When performed asynchronously then the status code is -put into req->async.status before the req->async.send_fn() callback is -called. - -Currently the most complete NTVFS backend is the CIFS backend. I don't -expect this backend will be used much in production, but it does -provide the ideal test case for our NTVFS design. As it offers the -full capabilities that are possible with a CIFS server we can be sure -that we don't have any gaping holes in our APIs, and that the front -end code is flexible enough to handle any advances in the NT style -feature sets of Unix filesystems that make come along. - - -Process Models --------------- - -In Samba3 we supported just one process model. It just so happens that -the process model that Samba3 supported is the "right" one for most -users, but there are situations where this model wasn't ideal. - -In Samba4 you can choose the smbd process model on the smbd command -line. - - -DCERPC binding strings ----------------------- - -When connecting to a dcerpc service you need to specify a binding -string. - -The format is: - - TRANSPORT:host[flags] - -where TRANSPORT is either ncacn_np for SMB or ncacn_ip_tcp for RPC/TCP - -"host" is an IP or hostname or netbios name. If the binding string -identifies the server side of an endpoint, "host" may be an empty -string. - -"flags" can include a SMB pipe name if using the ncacn_np transport or -a TCP port number if using the ncacn_ip_tcp transport, otherwise they -will be auto-determined. - -other recognised flags are: - - sign : enable ntlmssp signing - seal : enable ntlmssp sealing - spnego : use SPNEGO instead of NTLMSSP authentication - krb5 : use KRB5 instead of NTLMSSP authentication - connect : enable rpc connect level auth (auth, but no sign or seal) - validate : enable the NDR validator - print : enable debugging of the packets - bigendian : use bigendian RPC - padcheck : check reply data for non-zero pad bytes - - -Here are some examples: - - ncacn_np:myserver - ncacn_np:myserver[samr] - ncacn_np:myserver[\pipe\samr] - ncacn_np:myserver[/pipe/samr] - ncacn_np:myserver[samr,sign,print] - ncacn_np:myserver[sign,spnego] - ncacn_np:myserver[\pipe\samr,sign,seal,bigendian] - ncacn_np:myserver[/pipe/samr,seal,validate] - ncacn_np: - ncacn_np:[/pipe/samr] - ncacn_ip_tcp:myserver - ncacn_ip_tcp:myserver[1024] - ncacn_ip_tcp:myserver[sign,seal] - ncacn_ip_tcp:myserver[spnego,seal] - - -IDEA: Maybe extend UNC names like this? - - smbclient //server/share - smbclient //server/share[sign,seal,spnego] - -DCERPC Handles --------------- -The various handles that are used in the RPC servers should be created and -fetch using the dcesrv_handle_* functions. - -Use dcesrv_handle_new(struct dcesrv_connection *, uint8 handle_type) to obtain -a new handle of the specified type. Handle types are unique within each -pipe. - -The handle can later be fetched again using -struct dcesrv_handle *dcesrv_handle_fetch(struct dcesrv_connection *dce_conn, struct policy_handle *p, uint8 handle_type) -and destroyed by dcesrv_handle_destroy(struct dcesrv_handle *). - -User data should be stored in the 'data' member of the dcesrv_handle struct. - - -MSRPC ------ - - - - - ntvfs - - testing - - command line handling - - libcli structure - - posix reliance - - uid/gid handling - - process models - - static data - - msrpc - - -don't zero structures! avoid ZERO_STRUCT() and talloc_zero() - - -GMT vs TZ in printout of QFILEINFO timezones - -put in full UNC path in tconx - -test timezone handling by using a server in different zone from client - -do {} while (0) system - -NT_STATUS_IS_OK() is NOT the opposite of NT_STATUS_IS_ERR() - -need to implement secondary parts of trans2 and nttrans in server and -client - -document access_mask in openx reply - -check all capabilities and flag1, flag2 fields (eg. EAs) - -large files -> pass thru levels - -setpathinfo is very fussy about null termination of the file name - -the overwrite flag doesn't seem to work on setpathinfo RENAME_INFORMATION - -END_OF_FILE_INFORMATION and ALLOCATION_INFORMATION don't seem to work -via setpathinfo - -on w2k3 setpathinfo DISPOSITION_INFORMATION fails, but does have an -effect. It leaves the file with SHARING_VIOLATION. - -on w2k3 trans2 setpathinfo with any invalid low numbered level causes -the file to get into a state where DELETE_PENDING is reported, and the -file cannot be deleted until you reboot - -trans2 qpathinfo doesn't see the delete_pending flag correctly, but -qfileinfo does! - -get rid of pstring, fstring, strtok - -add programming documentation note about lp_set_cmdline() - -need to add a wct checking function in all client parsing code, -similar to REQ_CHECK_WCT() - -need to make sure that NTTIME is a round number of seconds when -converted from time_t - -not using a zero next offset in SMB_FILE_STREAM_INFORMATION for last -entry causes explorer exception under win2000 - - -if the server sets the session key the same for a second SMB socket as -an initial socket then the client will not re-authenticate, it will go -straight to a tconx, skipping session setup and will use all the -existing parameters! This allows two sockets with the same keys!? - - -removed blocking lock code, we now queue the whole request the same as -we queue any other pending request. This allows for things like a -close() while a pending blocking lock is being processed to operate -sanely. - -disabled change notify code - -disabled oplock code - - - -MILESTONES -========== - - -client library and test code ----------------------------- - - convert client library to new structure - get smbtorture working - get smbclient working - expand client library for all requests - write per-request test suite - gentest randomised test suite - separate client code as a library for non-Samba use - -server code ------------ - add remaining core SMB requests - add IPC layer - add nttrans layer - add rpc layer - fix auth models (share, server, rpc) - get net command working - connect CIFS backend to server level auth - get nmbd working - get winbindd working - reconnect printing code - restore removed smbd options - add smb.conf macro substitution code - add async backend notification - add generic timer event mechanism - -clustering code ---------------- - - write CIFS backend - new server models (break 1-1) - test clustered models - add fulcrum statistics gathering - -docs ----- - - conference paper - developer docs - -svn instructions - -Ideas ------ - - - store all config in config.ldb - - - load from smb.conf if modtime changes - - - dump full system config with ldbsearch - - - will need the ability to form a ldif difference file - - - advanced web admin via a web ldb editor - - - normal web admin via web forms -> ldif - - - config.ldb will replace smb.conf, secrets.tdb, shares.tdb etc - - - subsystems in smbd will load config parameters for a share - using ldbsearch at tconx time - - - need a loadparm equivalent module that provides parameter defaults - - - start smbd like this: "smbd -C tdb://etc/samba/config.ldb" or - "smbd -C ldapi://var/run/ldapi" - - - write a tool that generates a template ldap schema from an existing - ldb+tdb file - - - no need to HUP smbd to reload config - - - how to handle configuration comments? same problem as SWAT - - -BUGS: - add a test case for last_entry_offset in trans2 find interfaces - conn refused - connect -> errno - no 137 resolution not possible - should not fallback to anon when pass supplied - should check pass-thu cap bit, and skip lots of tests - possibly allow the test suite to say "allow oversized replies" for - trans2 and other calls - handle servers that don't have the setattre call in torture - add max file coponent length test and max path len test - check for alloc failure in all core reply.c and trans2.c code where - allocation size depends on client parameter - -case-insenstive idea: - all filenames on disk lowercase - real case in extended attribute - keep cache of what dirs are all lowercase - when searching for name, don't search if dir is definately all lowercase - when creating file, use dnotify to tell if someone else creates at - same time - -solve del *.* idea: - make mangle cache dynamic size - fill during a dir scan - setup a timer - destroy cache after 30 sec - destroy if a 2nd dir scan happens on same dir - diff --git a/prog_guide4.txt b/prog_guide4.txt new file mode 100644 index 00000000000..bba58b31b3b --- /dev/null +++ b/prog_guide4.txt @@ -0,0 +1,789 @@ + + +THIS IS INCOMPLETE! I'M ONLY COMMITING IT IN ORDER TO SOLICIT COMMENTS +FROM A FEW PEOPLE. DON'T TAKE THIS AS THE FINAL VERSION YET. + + +Samba4 Programming Guide +------------------------ + +The internals of Samba4 are quite different from previous versions of +Samba, so even if you are an experienced Samba developer please take +the time to read through this document. + +This document will explain both the broad structure of Samba4, and +some of the common coding elements such as memory management and +dealing with macros. + + +Coding Style +------------ + +In past versions of Samba we have basically let each programmer choose +their own programming style. Unfortunately the result has often been +that code that other members of the team find difficult to read. For +Samba version 4 I would like to standardise on a common coding style +to make the whole tree more readable. For those of you who are +horrified at the idea of having to learn a new style, I can assure you +that it isn't as painful as you might think. I was forced to adopt a +new style when I started working on the Linux kernel, and after some +initial pain found it quite easy. + +That said, I don't want to invent a new style, instead I would like to +adopt the style used by the Linux kernel. It is a widely used style +with plenty of support tools available. See Documentation/CodingStyle +in the Linux source tree. This is the style that I have used to write +all of the core infrastructure for Samba4 and I think that we should +continue with that style. + +I also think that we should most definately *not* adopt an automatic +reformatting system in cvs (or whatever other source code system we +end up using in the future). Such automatic formatters are, in my +experience, incredibly error prone and don't understand the necessary +exceptions. I don't mind if people use automated tools to reformat +their own code before they commit it, but please do not run such +automated tools on large slabs of existing code without being willing +to spend a *lot* of time hand checking the results. + +Finally, I think that for code that is parsing or formatting protocol +packets the code layout should strongly reflect the packet +format. That means ordring the code so that it parses in the same +order as the packet is stored on the wire (where possible) and using +white space to align packet offsets so that a reader can immediately +map any line of the code to the corresponding place in the packet. + + +Static and Global Data +---------------------- + +The basic rule is "avoid static and global data like the plague". What +do I mean by static data? The way to tell if you have static data in a +file is to use the "size" utility in Linux. For example if we run:: + + size libcli/raw/*.o + +in Samba4 then you get the following:: + + text data bss dec hex filename + 2015 0 0 2015 7df libcli/raw/clikrb5.o + 202 0 0 202 ca libcli/raw/clioplock.o + 35 0 0 35 23 libcli/raw/clirewrite.o + 3891 0 0 3891 f33 libcli/raw/clisession.o + 869 0 0 869 365 libcli/raw/clisocket.o + 4962 0 0 4962 1362 libcli/raw/clispnego.o + 1223 0 0 1223 4c7 libcli/raw/clitransport.o + 2294 0 0 2294 8f6 libcli/raw/clitree.o + 1081 0 0 1081 439 libcli/raw/raweas.o + 6765 0 0 6765 1a6d libcli/raw/rawfile.o + 6824 0 0 6824 1aa8 libcli/raw/rawfileinfo.o + 2944 0 0 2944 b80 libcli/raw/rawfsinfo.o + 541 0 0 541 21d libcli/raw/rawioctl.o + 1728 0 0 1728 6c0 libcli/raw/rawnegotiate.o + 723 0 0 723 2d3 libcli/raw/rawnotify.o + 3779 0 0 3779 ec3 libcli/raw/rawreadwrite.o + 6597 0 0 6597 19c5 libcli/raw/rawrequest.o + 5580 0 0 5580 15cc libcli/raw/rawsearch.o + 3034 0 0 3034 bda libcli/raw/rawsetfileinfo.o + 5187 0 0 5187 1443 libcli/raw/rawtrans.o + 2033 0 0 2033 7f1 libcli/raw/smb_signing.o + +notice that the "data" and "bss" columns are all zero? That is +good. If there are any non-zero values in data or bss then that +indicates static data and is bad (as a rule of thumb). + +Lets compare that result to the equivalent in Samba3:: + + text data bss dec hex filename + 3978 0 0 3978 f8a libsmb/asn1.o + 18963 0 288 19251 4b33 libsmb/cliconnect.o + 2815 0 1024 3839 eff libsmb/clidgram.o + 4038 0 0 4038 fc6 libsmb/clientgen.o + 3337 664 256 4257 10a1 libsmb/clierror.o + 10043 0 0 10043 273b libsmb/clifile.o + 332 0 0 332 14c libsmb/clifsinfo.o + 166 0 0 166 a6 libsmb/clikrb5.o + 5212 0 0 5212 145c libsmb/clilist.o + 1367 0 0 1367 557 libsmb/climessage.o + 259 0 0 259 103 libsmb/clioplock.o + 1584 0 0 1584 630 libsmb/cliprint.o + 7565 0 256 7821 1e8d libsmb/cliquota.o + 7694 0 0 7694 1e0e libsmb/clirap.o + 27440 0 0 27440 6b30 libsmb/clirap2.o + 2905 0 0 2905 b59 libsmb/clireadwrite.o + 1698 0 0 1698 6a2 libsmb/clisecdesc.o + 5517 0 0 5517 158d libsmb/clispnego.o + 485 0 0 485 1e5 libsmb/clistr.o + 8449 0 0 8449 2101 libsmb/clitrans.o + 2053 0 4 2057 809 libsmb/conncache.o + 3041 0 256 3297 ce1 libsmb/credentials.o + 1261 0 1024 2285 8ed libsmb/doserr.o + 14560 0 0 14560 38e0 libsmb/errormap.o + 3645 0 0 3645 e3d libsmb/namecache.o + 16815 0 8 16823 41b7 libsmb/namequery.o + 1626 0 0 1626 65a libsmb/namequery_dc.o + 14301 0 1076 15377 3c11 libsmb/nmblib.o + 24516 0 2048 26564 67c4 libsmb/nterr.o + 8661 0 8 8669 21dd libsmb/ntlmssp.o + 3188 0 0 3188 c74 libsmb/ntlmssp_parse.o + 4945 0 0 4945 1351 libsmb/ntlmssp_sign.o + 1303 0 0 1303 517 libsmb/passchange.o + 1221 0 0 1221 4c5 libsmb/pwd_cache.o + 2475 0 4 2479 9af libsmb/samlogon_cache.o + 10768 32 0 10800 2a30 libsmb/smb_signing.o + 4524 0 16 4540 11bc libsmb/smbdes.o + 5708 0 0 5708 164c libsmb/smbencrypt.o + 7049 0 3072 10121 2789 libsmb/smberr.o + 2995 0 0 2995 bb3 libsmb/spnego.o + 3186 0 0 3186 c72 libsmb/trustdom_cache.o + 1742 0 0 1742 6ce libsmb/trusts_util.o + 918 0 28 946 3b2 libsmb/unexpected.o + +notice all of the non-zero data and bss elements? Every bit of that +data is a bug waiting to happen. + +Static data is evil as it has the following consequences: +- it makes code much less likely to be thread-safe +- it makes code much less likely to be recursion-safe +- it leads to subtle side effects when the same code is called from + multiple places +- doesn't play well with shared libraries or plugins + +Static data is particularly evil in library code (such as our internal +smb and rpc libraries). If you can get rid of all static data in +libraries then you can make some fairly strong guarantees about the +behaviour of functions in that library, which really helps. + +Of course, it is possible to write code that uses static data and is +safe, it's just much harder to do that than just avoid static data in +the first place. We have been tripped up countless times by subtle +bugs in Samba due to the use of static data, so I think it is time to +start avoiding it in new code. Much of the core infrastructure of +Samba4 was specifically written to avoid static data, so I'm going to +be really annoyed if everyone starts adding lots of static data back +in. + +So, how do we avoid static data? The basic method is to use context +pointers. When reading the Samba4 code you will notice that just about +every function takes a pointer to a context structure as its first +argument. Any data that the function needs that isn't an explicit +argument to the function can be found by traversing that context. + +Note that this includes all of the little caches that we have lying +all over the code in Samba3. I'm referring to the ones that generally +have a "static int initialised" and then some static string or integer +that remembers the last return value of the function. Get rid of them! +If you are *REALLY* absolutely completely certain that your personal +favourite mini-cache is needed then you should do it properly by +putting it into the appropriate context rather than doing it the lazy +way by putting it inside the target function. I would suggest however +that the vast majority of those little caches are useless - don't +stick it in unless you have really firm benchmarking results that show +that it is needed and helps by a significant amount. + +Note that Samba4 is not yet completely clean of static data like +this. I've gotten the smbd/ directory down to 24 bytes of static data, +and libcli/raw/ down to zero. I've also gotten the ntvfs layer and all +backends down to just 8 bytes in ntvfs_base.c. The rest still needs +some more work. + +Also note that truly constant data is OK, and will not in fact show up +in the data and bss columns in "size" anyway (it will be included in +"text"). So you can have constant tables of protocol data. + + +How to use talloc +----------------- + +Please see the separate document, source/lib/talloc/talloc_guide.txt +You _must_ read this if you want to program in Samba4. + + +Interface Structures +-------------------- + +One of the biggest changes in Samba4 is the universal use of interface +structures. Go take a look through include/smb_interfaces.h now to get +an idea of what I am talking about. + +In Samba3 many of the core wire structures in the SMB protocol were +never explicitly defined in Samba. Instead, our parse and generation +functions just worked directly with wire buffers. The biggest problem +with this is that is tied our parse code with our "business logic" +much too closely, which meant the code got extremely confusing to +read. + +In Samba4 we have explicitly defined interface structures for +everything in the protocol. When we receive a buffer we always parse +it completely into one of these structures, then we pass a pointer to +that structure to a backend handler. What we must *not* do is make any +decisions about the data inside the parse functions. That is critical +as different backends will need different portions of the data. This +leads to a golden rule for Samba4: + + "don't design interfaces that lose information" + +In Samba3 our backends often received "condensed" versions of the +information sent from clients, but this inevitably meant that some +backends could not get at the data they needed to do what they wanted, +so from now on we should expose the backends to all of the available +information and let them choose which bits they want. + +Ok, so now some of you will be thinking "this sounds just like our +msrpc code from Samba3", and while to some extent this is true there +are extremely important differences in the approach that are worth +pointing out. + +In the Samba3 msrpc code we used explicit parse structures for all +msrpc functions. The problem is that we didn't just put all of the +real variables in these structures, we also put in all the artifacts +as well. A good example is the security descriptor strucrure that +looks like this in Samba3:: + + typedef struct security_descriptor_info + { + uint16 revision; + uint16 type; + + uint32 off_owner_sid; + uint32 off_grp_sid; + uint32 off_sacl; + uint32 off_dacl; + + SEC_ACL *dacl; + SEC_ACL *sacl; + DOM_SID *owner_sid; + DOM_SID *grp_sid; + } SEC_DESC; + +The problem with this structure is all the off_* variables. Those are +not part of the interface, and do not appear in any real descriptions +of Microsoft security descriptors. They are parsing artifacts +generated by the IDL compiler that Microsoft use. That doesn't mean +they aren't needed on the wire - indeed they are as they tell the +parser where to find the following four variables, but they should +*NOT* be in the interface structure. + +In Samba3 there were unwritten rules about which variables in a +structure a high level caller has to fill in and which ones are filled +in by the marshalling code. In Samba4 those rules are gone, because +the redundent artifact variables are gone. The high level caller just +sets up the real variables and the marshalling code worries about +generating the right offsets. + +The same rule applies to strings. In many places in the SMB and MSRPC +protocols complex strings are used on the wire, with complex rules +about padding, format, alighment, termination etc. None of that +information is useful to a high level calling routine or to a backend +- its all just so much wire fluff. So, in Samba4 these strings are +just "char *" and are always in our internal multi-byte format (which +is usually UTF8). It is up to the parse functions to worry about +translating the format and getting the padding right. + +The one exception to this is the use of the WIRE_STRING type, but that +has a very good justification in terms of regression testing. Go and +read the comment in smb_interfaces.h about that now. + +So, here is another rule to code by. When writing an interface +structure think carefully about what variables in the structure can be +left out as they are redundent. If some length is effectively defined +twice on the wire then only put it once in the packet. If a length can +be inferred from a null termination then do that and leave the length +out of the structure completely. Don't put redundent stuff in +structures! + + +Async Design +------------ + +Samba4 has an asynchronous design. That affects *lots* of the code, +and the implications of the asynchronous design needs to be considered +just about everywhere. + +The first aspect of the async design to look at is the SMB client +library. Lets take a look at the following three functions in +libcli/raw/rawfile.c:: + + struct cli_request *smb_raw_seek_send(struct cli_tree *tree, struct smb_seek *parms); + NTSTATUS smb_raw_seek_recv(struct cli_request *req, struct smb_seek *parms); + NTSTATUS smb_raw_seek(struct cli_tree *tree, struct smb_seek *parms); + +Go and read them now then come back. + +Ok, first notice there there are 3 separate functions, whereas the +equivalent code in Samba3 had just one. Also note that the 3rd +function is extremely simple - its just a wrapper around calling the +first two in order. + +The three separate functions are needed because we need to be able to +generate SMB calls asynchronously. The first call, which for smb calls +is always called smb_raw_XXXX_send(), constructs and sends a SMB +request and returns a "struct cli_request" which acts as a handle for +the request. The caller is then free to do lots of other calls if it +wants to, then when it is ready it can call the smb_raw_XXX_recv() +function to receive the reply. + +If all you want is a synchronous call then call the 3rd interface, the +one called smb_raw_XXXX(). That just calls the first two in order, and +blocks waiting for the reply. + +But what if you want to be called when the reply comes in? Yes, thats +possible. You can do things like this:: + + struct cli_request *req; + + req = smb_raw_XXX_send(tree, params); + + req->async.fn = my_callback; + req->async.private = my_private_data; + +then in your callback function you can call the smb_raw_XXXX_recv() +function to receive the reply. Your callback will receive the "req" +pointer, which you can use to retrieve your private data from +req->async.private. + +Then all you need to do is ensure that the main loop in the client +library gets called. You can either do that by polling the connection +using cli_transport_pending() and cli_request_receive_next() or you +can use transport->idle.func to setup an idle function handler to call +back to your main code. Either way, you can build a fully async +application. + +In order to support all of this we have to make sure that when we +write a piece of library code (SMB, MSRPC etc) that we build the +separate _send() and _recv() functions. It really is worth the effort. + +Now about async in smbd, a much more complex topic. + +The SMB protocol is inherently async. Some functions (such as change +notify) often don't return for hours, while hundreds of other +functions pass through the socket. Take a look at the RAW-MUX test in +the Samba4 smbtorture to see some really extreme examples of the sort +of async operations that Windows supports. I particularly like the +open/open/close sequence where the 2nd open (which conflicts with the +first) succeeds because the subsequent close is answered out of order. + +In Samba3 we handled this stuff very badly. We had awful "pending +request" queues that allocated full 128k packet buffers, and even with +all that crap we got the semantics wrong. In Samba4 I intend to make +sure we get this stuff right. + +So, how do we do this? We now have an async interface between smbd and +the NTVFS backends. Whenever smbd calls into a backend the backend has +an option of answer the request in a synchronous fashion if it wants +to just like in Samba3, but it also has the option of answering the +request asynchronously. The only backend that currently does this is +the CIFS backend, but I hope the other backends will soon do this to. + +To make this work you need to do things like this in the backend:: + + req->control_flags |= REQ_CONTROL_ASYNC; + +that tells smbd that the backend has elected to reply later rather +than replying immediately. The backend must *only* do this if +req->async.send_fn is not NULL. If send_fn is NULL then it means that +the smbd front end cannot handle this function being replied to in an +async fashion. + +If the backend does this then it is up to the backend to call +req->async.send_fn() when it is ready to reply. It the meantime smbd +puts the call on hold and goes back to answering other requests on the +socket. + +Inside smbd you will find that there is code to support this. The most +obvious change is that smbd splits each SMB reply function into two +parts - just like the client library has a _send() and _recv() +function, so smbd has a _send() function and the parse function for +each SMB. + +As an example go and have a look at reply_getatr_send() and +reply_getatr() in smb_server/reply.c. Read them? Good. + +Notice that reply_getatr() sets up the req->async structure to contain +the send function. Thats how the backend gets to do an async reply, it +calls this function when it is ready. Also notice that reply_getatr() +only does the parsing of the request, and does not do the reply +generation. That is done by the _send() function. + +The only missing piece in the Samba4 right now that prevents it being +fully async is that it currently does the low level socket calls (read +and write on sockets) in a blocking fashion. It does use select() to +make it somewhat async, but if a client were to send a partial packet +then delay before sending the rest then smbd would be stuck waiting +for the second half of the packet. + +To fix this I plan on making the socket calls async as well, which +luckily will not involve any API changes in the core of smbd or the +library. It just involves a little bit of extra code in clitransport.c +and smbd/request.c. As a side effect I hope that this will also reduce +the average number of system calls required to answer a request, so we +may see a performance improvement. + + +NTVFS +----- + +One of the most noticeable changes in Samba4 is the introduction of +the NTVFS layer. This provided the initial motivation for the design +of Samba4 and in many ways lies at the heart of the design. + +In Samba3 the main file serving process (smbd) combined the handling +of the SMB protocol with the mapping to POSIX semantics in the same +code. If you look in smbd/reply.c in Samba3 you see numerous places +where POSIX assumptions are mixed tightly with SMB parsing code. We +did have a VFS layer in Samba3, but it was a POSIX-like VFS layer, so +no matter how you wrote a plugin you could not bypass the POSIX +mapping decisions that had already been made before the VFS layer was +called. + +In Samba4 things are quite different. All SMB parsing is performed in +the smbd front end, then fully parsed requests are passed to the NTVFS +backend. That backend makes any semantic mapping decisions and fills +in the 'out' portion of the request. The front end is then responsible +for putting those results into wire format and sending them to the +client. + +Lets have a look at one of those request structures. Go and read the +definition of "union smb_write" and "enum write_level" in +include/smb_interfaces.h. (no, don't just skip reading it, really go +and read it. Yes, that means you!). + +Notice the union? That's how Samba4 allows a single NTVFS backend +interface to handle the several different ways of doing a write +operation in the SMB protocol. Now lets look at one section of that +union:: + + /* SMBwriteX interface */ + struct { + enum write_level level; + + struct { + uint16 fnum; + SMB_BIG_UINT offset; + uint16 wmode; + uint16 remaining; + uint32 count; + const char *data; + } in; + struct { + uint32 nwritten; + uint16 remaining; + } out; + } writex; + +see the "in" and "out" sections? The "in" section is for parameters +that the SMB client sends on the wire as part of the request. The smbd +front end parse code parses the wire request and fills in all those +parameters. It then calls the NTVFS interface which looks like this:: + + NTSTATUS (*write)(struct request_context *req, union smb_write *io); + +and the NTVFS backend does the write request. The backend then fills +in the "out" section of the writex structure and gives the union back +to the front end (either by returning, or if done in an async fashion +then by calling the async send function. See the async discussion +elsewhere in this document). + +The NTVFS backend knows which particular function is being requested +by looking at io->generic.level. Notice that this enum is also +repeated inside each of the sub-structures in the union, so the +backend could just as easily look at io->writex.level and would get +the same variable. + +Notice also that some levels (such as splwrite) don't have an "out" +section. This happens because there is no return value apart from a +status code from those SMB calls. + +So what about status codes? The status code is returned directly by +the backend NTVFS interface when the call is performed +synchronously. When performed asynchronously then the status code is +put into req->async.status before the req->async.send_fn() callback is +called. + +Currently the most complete NTVFS backend is the CIFS backend. I don't +expect this backend will be used much in production, but it does +provide the ideal test case for our NTVFS design. As it offers the +full capabilities that are possible with a CIFS server we can be sure +that we don't have any gaping holes in our APIs, and that the front +end code is flexible enough to handle any advances in the NT style +feature sets of Unix filesystems that make come along. + + +Process Models +-------------- + +In Samba3 we supported just one process model. It just so happens that +the process model that Samba3 supported is the "right" one for most +users, but there are situations where this model wasn't ideal. + +In Samba4 you can choose the smbd process model on the smbd command +line. + + +DCERPC binding strings +---------------------- + +When connecting to a dcerpc service you need to specify a binding +string. + +The format is: + + TRANSPORT:host[flags] + +where TRANSPORT is either ncacn_np for SMB or ncacn_ip_tcp for RPC/TCP + +"host" is an IP or hostname or netbios name. If the binding string +identifies the server side of an endpoint, "host" may be an empty +string. + +"flags" can include a SMB pipe name if using the ncacn_np transport or +a TCP port number if using the ncacn_ip_tcp transport, otherwise they +will be auto-determined. + +other recognised flags are: + + sign : enable ntlmssp signing + seal : enable ntlmssp sealing + spnego : use SPNEGO instead of NTLMSSP authentication + krb5 : use KRB5 instead of NTLMSSP authentication + connect : enable rpc connect level auth (auth, but no sign or seal) + validate : enable the NDR validator + print : enable debugging of the packets + bigendian : use bigendian RPC + padcheck : check reply data for non-zero pad bytes + + +Here are some examples: + + ncacn_np:myserver + ncacn_np:myserver[samr] + ncacn_np:myserver[\pipe\samr] + ncacn_np:myserver[/pipe/samr] + ncacn_np:myserver[samr,sign,print] + ncacn_np:myserver[sign,spnego] + ncacn_np:myserver[\pipe\samr,sign,seal,bigendian] + ncacn_np:myserver[/pipe/samr,seal,validate] + ncacn_np: + ncacn_np:[/pipe/samr] + ncacn_ip_tcp:myserver + ncacn_ip_tcp:myserver[1024] + ncacn_ip_tcp:myserver[sign,seal] + ncacn_ip_tcp:myserver[spnego,seal] + + +IDEA: Maybe extend UNC names like this? + + smbclient //server/share + smbclient //server/share[sign,seal,spnego] + +DCERPC Handles +-------------- +The various handles that are used in the RPC servers should be created and +fetch using the dcesrv_handle_* functions. + +Use dcesrv_handle_new(struct dcesrv_connection *, uint8 handle_type) to obtain +a new handle of the specified type. Handle types are unique within each +pipe. + +The handle can later be fetched again using +struct dcesrv_handle *dcesrv_handle_fetch(struct dcesrv_connection *dce_conn, struct policy_handle *p, uint8 handle_type) +and destroyed by dcesrv_handle_destroy(struct dcesrv_handle *). + +User data should be stored in the 'data' member of the dcesrv_handle struct. + + +MSRPC +----- + + + + - ntvfs + - testing + - command line handling + - libcli structure + - posix reliance + - uid/gid handling + - process models + - static data + - msrpc + + +don't zero structures! avoid ZERO_STRUCT() and talloc_zero() + + +GMT vs TZ in printout of QFILEINFO timezones + +put in full UNC path in tconx + +test timezone handling by using a server in different zone from client + +do {} while (0) system + +NT_STATUS_IS_OK() is NOT the opposite of NT_STATUS_IS_ERR() + +need to implement secondary parts of trans2 and nttrans in server and +client + +document access_mask in openx reply + +check all capabilities and flag1, flag2 fields (eg. EAs) + +large files -> pass thru levels + +setpathinfo is very fussy about null termination of the file name + +the overwrite flag doesn't seem to work on setpathinfo RENAME_INFORMATION + +END_OF_FILE_INFORMATION and ALLOCATION_INFORMATION don't seem to work +via setpathinfo + +on w2k3 setpathinfo DISPOSITION_INFORMATION fails, but does have an +effect. It leaves the file with SHARING_VIOLATION. + +on w2k3 trans2 setpathinfo with any invalid low numbered level causes +the file to get into a state where DELETE_PENDING is reported, and the +file cannot be deleted until you reboot + +trans2 qpathinfo doesn't see the delete_pending flag correctly, but +qfileinfo does! + +get rid of pstring, fstring, strtok + +add programming documentation note about lp_set_cmdline() + +need to add a wct checking function in all client parsing code, +similar to REQ_CHECK_WCT() + +need to make sure that NTTIME is a round number of seconds when +converted from time_t + +not using a zero next offset in SMB_FILE_STREAM_INFORMATION for last +entry causes explorer exception under win2000 + + +if the server sets the session key the same for a second SMB socket as +an initial socket then the client will not re-authenticate, it will go +straight to a tconx, skipping session setup and will use all the +existing parameters! This allows two sockets with the same keys!? + + +removed blocking lock code, we now queue the whole request the same as +we queue any other pending request. This allows for things like a +close() while a pending blocking lock is being processed to operate +sanely. + +disabled change notify code + +disabled oplock code + + + +MILESTONES +========== + + +client library and test code +---------------------------- + + convert client library to new structure + get smbtorture working + get smbclient working + expand client library for all requests + write per-request test suite + gentest randomised test suite + separate client code as a library for non-Samba use + +server code +----------- + add remaining core SMB requests + add IPC layer + add nttrans layer + add rpc layer + fix auth models (share, server, rpc) + get net command working + connect CIFS backend to server level auth + get nmbd working + get winbindd working + reconnect printing code + restore removed smbd options + add smb.conf macro substitution code + add async backend notification + add generic timer event mechanism + +clustering code +--------------- + + write CIFS backend + new server models (break 1-1) + test clustered models + add fulcrum statistics gathering + +docs +---- + + conference paper + developer docs + +svn instructions + +Ideas +----- + + - store all config in config.ldb + + - load from smb.conf if modtime changes + + - dump full system config with ldbsearch + + - will need the ability to form a ldif difference file + + - advanced web admin via a web ldb editor + + - normal web admin via web forms -> ldif + + - config.ldb will replace smb.conf, secrets.tdb, shares.tdb etc + + - subsystems in smbd will load config parameters for a share + using ldbsearch at tconx time + + - need a loadparm equivalent module that provides parameter defaults + + - start smbd like this: "smbd -C tdb://etc/samba/config.ldb" or + "smbd -C ldapi://var/run/ldapi" + + - write a tool that generates a template ldap schema from an existing + ldb+tdb file + + - no need to HUP smbd to reload config + + - how to handle configuration comments? same problem as SWAT + + +BUGS: + add a test case for last_entry_offset in trans2 find interfaces + conn refused + connect -> errno + no 137 resolution not possible + should not fallback to anon when pass supplied + should check pass-thu cap bit, and skip lots of tests + possibly allow the test suite to say "allow oversized replies" for + trans2 and other calls + handle servers that don't have the setattre call in torture + add max file coponent length test and max path len test + check for alloc failure in all core reply.c and trans2.c code where + allocation size depends on client parameter + +case-insenstive idea: + all filenames on disk lowercase + real case in extended attribute + keep cache of what dirs are all lowercase + when searching for name, don't search if dir is definately all lowercase + when creating file, use dnotify to tell if someone else creates at + same time + +solve del *.* idea: + make mangle cache dynamic size + fill during a dir scan + setup a timer + destroy cache after 30 sec + destroy if a 2nd dir scan happens on same dir + -- cgit v1.2.1