From 8f8a9f01909ba29e2b781310baeeaaddc3f15f0d Mon Sep 17 00:00:00 2001 From: "Gerald W. Carter" Date: Tue, 22 Apr 2008 10:09:40 -0500 Subject: Moving docs tree to docs-xml to make room for generated docs in the release tarball. (This used to be commit 9f672c26d63955f613088489c6efbdc08b5b2d14) --- docs-xml/Samba3-HOWTO/TOSHARG-SWAT.xml | 640 +++++++++++++++++++++++++++++++++ 1 file changed, 640 insertions(+) create mode 100644 docs-xml/Samba3-HOWTO/TOSHARG-SWAT.xml (limited to 'docs-xml/Samba3-HOWTO/TOSHARG-SWAT.xml') diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-SWAT.xml b/docs-xml/Samba3-HOWTO/TOSHARG-SWAT.xml new file mode 100644 index 00000000000..73b092f7f06 --- /dev/null +++ b/docs-xml/Samba3-HOWTO/TOSHARG-SWAT.xml @@ -0,0 +1,640 @@ + + + + + &author.jht; + April 21, 2003 + + +SWAT: The Samba Web Administration Tool + + +configuration tool +SWAT +Web-based configuration +There are many and varied opinions regarding the usefulness of SWAT. No matter how hard one tries to produce +the perfect configuration tool, it remains an object of personal taste. SWAT is a tool that allows Web-based +configuration of Samba. It has a wizard that may help to get Samba configured quickly, it has +context-sensitive help on each &smb.conf; parameter, it provides for monitoring of current state of connection +information, and it allows networkwide MS Windows network password management. + + + +Features and Benefits + + +internetworking super daemon +SWAT is a facility that is part of the Samba suite. The main executable is called +swat and is invoked by the internetworking super daemon. +See appropriate section for details. + + + +man +SWAT uses integral Samba components to locate parameters supported by the particular +version of Samba. Unlike tools and utilities that are external to Samba, SWAT is always +up to date as known Samba parameters change. SWAT provides context-sensitive help for each +configuration parameter, directly from man page entries. + + + +documentation +configuration files +internal ordering +Some network administrators believe that it is a good idea to write systems +documentation inside configuration files, and for them SWAT will always be a nasty tool. SWAT +does not store the configuration file in any intermediate form; rather, it stores only the +parameter settings, so when SWAT writes the &smb.conf; file to disk, it writes only +those parameters that are at other than the default settings. The result is that all comments, +as well as parameters that are no longer supported, will be lost from the &smb.conf; file. +Additionally, the parameters will be written back in internal ordering. + + + +stripped of comments +Before using SWAT, please be warned &smbmdash; SWAT will completely replace your &smb.conf; with +a fully optimized file that has been stripped of all comments you might have placed there +and only nondefault settings will be written to the file. + + + + + +Guidelines and Technical Tips + + +internationalization support +This section aims to unlock the dark secrets behind how SWAT may be made to work, +how it can be made more secure, and how to solve internationalization support problems. + + + +Validate SWAT Installation + + +SWAT binary support +The very first step that should be taken before attempting to configure a host +system for SWAT operation is to check that it is installed. This may seem a trivial +point to some, but several Linux distributions do not install SWAT by default, +even though they do ship an installable binary support package containing SWAT +on the distribution media. + + + +swat +When you have confirmed that SWAT is installed, it is necessary to validate +that the installation includes the binary swat file as well +as all the supporting text and Web files. A number of operating system distributions +in the past have failed to include the necessary support files, even though the +swat binary executable file was installed. + + + +inetd +xinetd +Finally, when you are sure that SWAT has been fully installed, please check that SWAT +is enabled in the control file for the internetworking super-daemon (inetd or xinetd) +that is used on your operating system platform. + + + +Locating the <command>SWAT</command> File + + +/usr/local/samba/bin +/usr/sbin +/opt/samba/bin +To validate that SWAT is installed, first locate the swat binary +file on the system. It may be found under the following directories: + + /usr/local/samba/bin &smbmdash; the default Samba location + /usr/sbin &smbmdash; the default location on most Linux systems + /opt/samba/bin + + + + +The actual location is much dependent on the choice of the operating system vendor or as determined +by the administrator who compiled and installed Samba. + + + +There are a number of methods that may be used to locate the swat binary file. +The following methods may be helpful. + + + +swat +operating system search path +swat command-line options +If swat is in your current operating system search path, it will be easy to +find it. You can ask what are the command-line options for swat as shown here: + +frodo:~ # swat -? +Usage: swat [OPTION...] + -a, --disable-authentication Disable authentication (demo mode) + +Help options: + -?, --help Show this help message + --usage Display brief usage message + +Common samba options: + -d, --debuglevel=DEBUGLEVEL Set debug level + -s, --configfile=CONFIGFILE Use alternative configuration file + -l, --log-basename=LOGFILEBASE Basename for log/debug files + -V, --version Print version + + + + + + +Locating the SWAT Support Files + + +Now that you have found that swat is in the search path, it is easy +to identify where the file is located. Here is another simple way this may be done: + +frodo:~ # whereis swat +swat: /usr/sbin/swat /usr/share/man/man8/swat.8.gz + + + + +If the above measures fail to locate the swat binary, another approach +is needed. The following may be used: + +frodo:/ # find / -name swat -print +/etc/xinetd.d/swat +/usr/sbin/swat +/usr/share/samba/swat +frodo:/ # + + + + +This list shows that there is a control file for xinetd, the internetwork +super-daemon that is installed on this server. The location of the SWAT binary file is +/usr/sbin/swat, and the support files for it are located under the +directory /usr/share/samba/swat. + + + +We must now check where swat expects to find its support files. This can +be done as follows: + +frodo:/ # strings /usr/sbin/swat | grep "/swat" +/swat/ +... +/usr/share/samba/swat +frodo:/ # + + + + +The /usr/share/samba/swat/ entry shown in this listing is the location of the +support files. You should verify that the support files exist under this directory. A sample +list is as shown: + +jht@frodo:/> find /usr/share/samba/swat -print +/usr/share/samba/swat +/usr/share/samba/swat/help +/usr/share/samba/swat/lang +/usr/share/samba/swat/lang/ja +/usr/share/samba/swat/lang/ja/help +/usr/share/samba/swat/lang/ja/help/welcome.html +/usr/share/samba/swat/lang/ja/images +/usr/share/samba/swat/lang/ja/images/home.gif +... +/usr/share/samba/swat/lang/ja/include +/usr/share/samba/swat/lang/ja/include/header.nocss.html +... +/usr/share/samba/swat/lang/tr +/usr/share/samba/swat/lang/tr/help +/usr/share/samba/swat/lang/tr/help/welcome.html +/usr/share/samba/swat/lang/tr/images +/usr/share/samba/swat/lang/tr/images/home.gif +... +/usr/share/samba/swat/lang/tr/include +/usr/share/samba/swat/lang/tr/include/header.html +/usr/share/samba/swat/using_samba +... +/usr/share/samba/swat/images +/usr/share/samba/swat/images/home.gif +... +/usr/share/samba/swat/include +/usr/share/samba/swat/include/footer.html +/usr/share/samba/swat/include/header.html +jht@frodo:/> + + + + +If the files needed are not available, it is necessary to obtain and install them +before SWAT can be used. + + + + + + +Enabling SWAT for Use + + +SWAT should be installed to run via the network super-daemon. Depending on which system +your UNIX/Linux system has, you will have either an inetd- or +xinetd-based system. + + + +The nature and location of the network super-daemon varies with the operating system +implementation. The control file (or files) can be located in the file +/etc/inetd.conf or in the directory /etc/[x]inet[d].d +or in a similar location. + + + +The control entry for the older style file might be: +swatenable + + + + + # swat is the Samba Web Administration Tool + swat stream tcp nowait.400 root /usr/sbin/swat swat + + + +A control file for the newer style xinetd could be: + + + + +# default: off +# description: SWAT is the Samba Web Admin Tool. Use swat \ +# to configure your Samba server. To use SWAT, \ +# connect to port 901 with your favorite web browser. +service swat +{ + port = 901 + socket_type = stream + wait = no + only_from = localhost + user = root + server = /usr/sbin/swat + log_on_failure += USERID + disable = no +} + +In the above, the default setting for disable is yes. +This means that SWAT is disabled. To enable use of SWAT, set this parameter to no +as shown. + + + +swat +/usr/sbin +/usr/share/samba/swat +/usr/local/samba/swat +Both of the previous examples assume that the swat binary has been +located in the /usr/sbin directory. In addition to the above, +SWAT will use a directory access point from which it will load its Help files +as well as other control information. The default location for this on most Linux +systems is in the directory /usr/share/samba/swat. The default +location using Samba defaults will be /usr/local/samba/swat. + + + +SWAT permission allowed +password change facility +Access to SWAT will prompt for a logon. If you log onto SWAT as any non-root user, +the only permission allowed is to view certain aspects of configuration as well as +access to the password change facility. The buttons that will be exposed to the non-root +user are HOME, STATUS, VIEW, and +PASSWORD. The only page that allows +change capability in this case is PASSWORD. + + + +As long as you log onto SWAT as the user root, you should obtain +full change and commit ability. The buttons that will be exposed include +HOME, GLOBALS, SHARES, PRINTERS, +WIZARD, STATUS, VIEW, and PASSWORD. + + + + + +Securing SWAT through SSL + + + +SSL +swatsecurity +Many people have asked about how to set up SWAT with SSL to allow for secure remote +administration of Samba. Here is a method that works, courtesy of Markus Krieger. + + + +Modifications to the SWAT setup are as follows: + + + + +OpenSSL + Install OpenSSL. + + + +certificate +private key + Generate certificate and private key. +/usr/bin/openssl + +&rootprompt;/usr/bin/openssl req -new -x509 -days 365 -nodes -config \ + /usr/share/doc/packages/stunnel/stunnel.cnf \ + -out /etc/stunnel/stunnel.pem -keyout /etc/stunnel/stunnel.pem + + + + Remove SWAT entry from [x]inetd. + + + +stunnel + Start stunnel. + + +&rootprompt;stunnel -p /etc/stunnel/stunnel.pem -d 901 \ + -l /usr/local/samba/bin/swat swat + + + + +Afterward, simply connect to SWAT by using the URL https://myhost:901, accept the certificate, and the SSL connection is up. + + + + + +Enabling SWAT Internationalization Support + + +SWAT can be configured to display its messages to match the settings of +the language configurations of your Web browser. It will be passed to SWAT +in the Accept-Language header of the HTTP request. + + + +To enable this feature: + + + + + Install the proper msg files from the Samba + source/po directory into $LIBDIR. + + + + Set your browsers language setting. + + + + +msg file +Japanese +French +English +The name of the msg file is the same as the language ID sent by the browser. For +example, en means English, ja means Japanese, fr means French. + + + +locale +If you do not like some of messages, or there are no msg files for +your locale, you can create them simply by copying the en.msg files +to the directory for your language ID.msg and filling in proper strings +to each msgstr. For example, in it.msg, the +msg file for the Italian locale, just set: + +msgid "Set Default" +msgstr "Imposta Default" + +msg +and so on. If you find a mistake or create a new msg file, please email it +to us so we will consider it in the next release of Samba. The msg file should be encoded in UTF-8. + + + +UTF-8 encoding +Note that if you enable this feature and the is not +matched to your browser's setting, the SWAT display may be corrupted. In a future version of +Samba, SWAT will always display messages with UTF-8 encoding. You will then not need to set +this &smb.conf; file parameter. + + + + + + + +Overview and Quick Tour + + +SWAT is a tool that may be used to configure Samba or just to obtain useful links +to important reference materials such as the contents of this book as well as other +documents that have been found useful for solving Windows networking problems. + + + +The SWAT Home Page + + +The SWAT title page provides access to the latest Samba documentation. The manual page for +each Samba component is accessible from this page, as are the Samba3-HOWTO (this +document) as well as the O'Reilly book Using Samba. + + + +Administrators who wish to validate their Samba configuration may obtain useful information +from the man pages for the diagnostic utilities. These are available from the SWAT home page +also. One diagnostic tool that is not mentioned on this page but that is particularly +useful is ethereal. + + + +SWAT can be configured to run in demo mode. This is not recommended +because it runs SWAT without authentication and with full administrative ability. It allows +changes to &smb.conf; as well as general operation with root privileges. The option that +creates this ability is the flag to SWAT. Do not use this in a +production environment. + + + + + +Global Settings + + +The GLOBALS button exposes a page that allows configuration of the global parameters +in &smb.conf;. There are two levels of exposure of the parameters: + + + + + Basic &smbmdash; exposes common configuration options. + + + + Advanced &smbmdash; exposes configuration options needed in more + complex environments. + + + + +To switch to other than Basic editing ability, click on Advanced. +You may also do this by clicking on the radio button, then click on the Commit Changes button. + + + +After making any changes to configuration parameters, make sure that +you click on the +Commit Changes button before moving to another area; otherwise, +your changes will be lost. + + + +SWAT has context-sensitive help. To find out what each parameter is +for, simply click on the +Help link to the left of the configuration parameter. + + + + + +Share Settings + + +To affect a currently configured share, simply click on the pull-down button between the +Choose Share and the Delete Share buttons and +select the share you wish to operate on. To edit the settings, +click on the +Choose Share button. To delete the share, simply press the +Delete Share button. + + + +To create a new share, next to the button labeled Create Share, enter +into the text field the name of the share to be created, then click on the +Create Share button. + + + + + +Printers Settings + + +To affect a currently configured printer, simply click on the pull-down button between the +Choose Printer and the Delete Printer buttons and +select the printer you wish to operate on. To edit the settings, +click on the +Choose Printer button. To delete the share, simply press the +Delete Printer button. + + + +To create a new printer, next to the button labeled Create Printer, enter +into the text field the name of the share to be created, then click on the +Create Printer button. + + + + + +The SWAT Wizard + + +The purpose of the SWAT Wizard is to help the Microsoft-knowledgeable network administrator +to configure Samba with a minimum of effort. + + + +The Wizard page provides a tool for rewriting the &smb.conf; file in fully optimized format. +This will also happen if you press the Commit button. The two differ +because the Rewrite button ignores any changes that may have been made, +while the Commit button causes all changes to be affected. + + + +The Edit button permits the editing (setting) of the minimal set of +options that may be necessary to create a working Samba server. + + + +Finally, there are a limited set of options that determine what type of server Samba +will be configured for, whether it will be a WINS server, participate as a WINS client, or +operate with no WINS support. By clicking one button, you can elect to expose (or not) user +home directories. + + + + + +The Status Page + + +The status page serves a limited purpose. First, it allows control of the Samba daemons. +The key daemons that create the Samba server environment are &smbd;, &nmbd;, and &winbindd;. + + + +The daemons may be controlled individually or as a total group. Additionally, you may set +an automatic screen refresh timing. As MS Windows clients interact with Samba, new smbd processes +are continually spawned. The auto-refresh facility allows you to track the changing +conditions with minimal effort. + + + +Finally, the status page may be used to terminate specific smbd client connections in order to +free files that may be locked. + + + + + +The View Page + + +The view page allows you to view the optimized &smb.conf; file and, if you are +particularly masochistic, permits you also to see all possible global configuration +parameters and their settings. + + + + + +The Password Change Page + + +The password change page is a popular tool that allows the creation, deletion, deactivation, +and reactivation of MS Windows networking users on the local machine. You can also use +this tool to change a local password for a user account. + + + +When logged in as a non-root account, the user must provide the old password as well as +the new password (twice). When logged in as root, only the new password is +required. + + + +One popular use for this tool is to change user passwords across a range of remote MS Windows +servers. + + + + + + -- cgit