How to install createusers
==========================

Contents
--------
- Requirements
- Optional packages
- For the impatient
- Installing createusers
- Configuring basic options
- Configuring MySQL support
- Configuring PostgreSQL support
- Configuring Samba support
- Configuring user quota support
- MySQL and quota support  
- Testing
- Apache configuration for personal webspace
- Web User Interface
- PhpMyAdmin configuration
- Creating users files the lazy way 


Requirements
------------

To use createusers you must have the following:

Bash shell (/bin/bash)
Expect scripting language (/usr/bin/expect)
Perl scripting language (/usr/bin/perl)
TCL scripting language (Expect is based upon this)
Sed stream editor 


Optional packages
-----------------

Apache 1.3.12 or later
MySQL server 3.23 or later
MySQL client required for MySQL server 
PostgreSQL server 7.0.3 or later
PostgreSQL client package required if PostgreSQL installed
Samba server
Quota support in the Linux kernel.


For the impatient
-----------------

1. Run install.sh
2. Edit /etc/createusers.conf
3. Add some sample users with this command:

    createusers users.sample

4. The sample users should be created.


Installing createusers
----------------------

1. Become root, if you are not already, with the following command:
  
     su -

2. Install with the following command: 

     sh install.sh

3. You will be asked for the location of your system's command (section 1)
   manual pages. If you are unsure, check your system's documentation.
   Typical locations are (Red Hat 7.x):

      /usr/share/man/man1

   or (some other distributions)

      /usr/man/man1

   You may find you cannot backspace while typing in the directory name.
   If you are a truly inaccurate typist, the following command will
   save you typing the directory name when prompted:

     echo "/usr/share/man/man1" | sh install.sh

4. Createusers and its supporting programs will be installed.


Configuring basic options
-------------------------

1. Edit the /etc/createusers.conf file.  

2. To give each new user their own home directory, uncomment the 
   'create_home_dir' parameter. Note that Red Hat systems may 
   automatically create home directories, even if not actually 
   instructed to do so.

3. To give users personal webspace in their home directory, 
   uncomment the 'create_html_dir' parameter. This works with the
   'UserDir' directive of the Apache web server.

4. If you want to change the user's default login shell, alter the
   'default_shell' parameter.

5. Save changes to /etc/createusers.conf.


Configuring MySQL support
-------------------------

1. To give each new user a personal MySQL database, the MySQL server
   must be prepared. 

   Ensure that the MySQL client package is installed on the local machine.
   Log in on the machine where MySQL is running. This can be a local or
   a remote machine. Ensure mysqld is running and the MySQL root password 
   has been set. If the MySQL root password has not been set, use the 
   mysqladmin program supplied with MySQL to set it, eg:  

     mysqladmin -u root password your_password

   Substitute the password of your choice for 'your_password'. This will
   set the MySQL root password. Note that MySQL passwords are separate
   to the Unix login passwords.

2. If MySQL is running on the local machine, skip on to step 3. If MySQL 
   is running on a remote machine, and you wish to add users to it 
   remotely, you must allow remote administrator access to MySQL.

   Log on to the machine where MySQL is running. Allow remote administrator
   access using the mysql program, eg:

     mysql -u root -p -e "GRANT ALL PRIVILEGES on mysql.* to
     root@your_host identified by 'your_password';"

   Substitute the name of the host on which createusers is installed
   for 'your_host'. Substitute the password of your choice for
   'your password'. Note the remote root password is separate from the
   local root password. You can make the remote and local root passwords
   the same or different, you may decide either way.
   
   Enter the MySQL root password when prompted. This allows 
   the MySQL server's authentication database to be modified by the MySQL
   root user, when connecting from the specified host.
        
3. Go to the machine on which createusers is installed, if you are
   not there already. Log on as root and edit the file:

     ~/.my.cnf

   This is the MySQL client configuration file, which is located in
   the home directory of the root user (/root). The permissions on this 
   file are read-write for root and no access for all other users. The file
   is created and its permissions set by the createusers installation script.
   The contents of the file will be as follows:

     [client]
     #password=

   Set the password parameter to the MySQL root password, and uncomment 
   the password line. Eg, if the password is 'root', the file should read:

     [client]
     password=root

   Once ~/.my.cnf is correctly set up, the root user of the system
   will no longer have to enter a password manually when accessing MySQL using 
   'mysql' or 'mysqladmin'. This is essential for createusers to work.

4. Save changes to ~/.my.cnf.

5. Edit /etc/createusers.conf.

6. Ensure the make_user_databases parameter is uncommented. 

7. Set the 'mysql_server' parameter to the host name on which the 
   MySQL server is running. If MySQL is running on the local machine,
   the parameter value must be 'localhost'.

8. Set 'mysql_allowed_hosts' to the host names from which users will 
   connect to the MySQL server. If the MySQL server is running locally, 
   the allowed hosts must be 'localhost' and the full host name of the 
   local machine.

9. Save changes to /etc/createusers.conf.


Configuring PostgreSQL support
------------------------------

These instructions assume the PostgreSQL server is running on the local
machine and it has been initialised according to the instructions
in the PosgreSQL package.

1. Set the 'postgres' master user's password. By default, PostgreSQL
   allows all users on the local machine access to any PostgreSQL account,
   including the master account. To set the master account password, connect
   to PostgreSQL as the master user, like this: 

     psql -U postgres

2. You should now be connected. The prompt indicates you are connected as
   the 'postgres' user and the hash means you have all privileges.
   To set the password, use this command:

     alter user postgres with password 'your_password'

   Substitute the password of your choice for 'your_password'.

3. Disconnect from PostgreSQL with this command:

     \q

4. Next, edit the PostgreSQL access policy configuration file:

     /var/lib/pgsql/pg_hba.conf

   The name of the file stands for PostgreSQL Host Based Access. 

5. Change the last two lines of the file so it reads:

     # By default, allow anything over UNIX domain sockets and localhost.
     local      all                                           password
     host       all         127.0.0.1     255.255.255.255     password

6. Save changes to /var/lib/pgsql/pg_hba.conf. This causes PostgreSQL
   to require a password for all access from the local host. The change 
   takes effect immediately.

7. Edit ~/.pg.password. 

8. This file must contain the PostgreSQL master account password. For
   example, if the PostgreSQL master account password is 'root', the
   ~/.pg.password file must contain:

     root

   The password must start at the beginning of the line. There should
   not be white space above or below the password. The permissions on 
   ~/.pg.password are set to read and write for root and no access for
   all other users. The permissions are set automatically by the 
   createusers installation script.

9. Save changes to ~/.pg.password.

10. Edit /etc/createusers.conf.

11. Ensure the 'create_postgres_databases' parameter is uncommented.

12. Set the 'postgres_server' parameter to the host name of the machine
    running the PostgreSQL server. The default is 'localhost'. If the 
    PostgreSQL server is on a remote machine, the remote PostgreSQL server 
    must be configured to allow access from the machine running createusers. 

13. Save changes to /etc/createusers.conf.
    

Configuring Samba support
-------------------------

1. Ensure Samba is installed on the local machine.

2. Edit /etc/createusers.conf.

3. Ensure 'create_samba_users' is uncommented. This controls whether 
   createusers will attempt to create Samba accounts. Createusers
   relies on the smbpasswd command to create Samba accounts.

4. Ensure the 'smbpasswd_file' parameter is set to the location of the 
   'smbpasswd' Samba user authentication file on the local machine.
   If you are unsure, check the 'smb.conf' Samba configuration file.

   On some distributions of Samba, the 'smbpasswd' file is not created
   automatically when Samba is installed. To ensure this, find out
   the location of 'smbpasswd' from the 'smb.conf' file and create
   an empty file in that location. For example, if the Samba password
   file is configured to be '/etc/smbpasswd', use this command: 

     touch /etc/smbpasswd

5. Save changes to /etc/createusers.conf.


Configuring user quota support
------------------------------

1. Ensure that support for user disk quota is compiled into the kernel.
   Standard precompiled kernels include quota support.

2. Turn on quota for the filesystem on which the users' files will reside.
   If you have Linuxconf, turn on quota using Linuxconf. If you do not
   have Linuxconf, check your system's documentation to see how to turn
   on quota. If you need more help, see the Quota HOWTO at 
   http://www.linuxdoc.org/.

3. Create a user called 'quotadefault'. Set the quota of this user using
   Linuxconf if you have that. Alternatively use the 'edquota' utility.
   Edquota invokes a text editor for altering a user's quota. Set the
   editor to the one of your choice with this command:
   
     export EDITOR=pico
     
   This will cause the user's quota to be edited with 'pico'. Substitute
   the editor of your choice, for example, 'gedit' for 'pico'. The command 
   to edit the quota of the 'quotadefault' user is:
   
     edquota quotadefault
     
   See the edquota man page (man edquota) for more instructions.

4. Edit /etc/createusers.conf.

5. Uncomment the line beginning 'quota_prototype_user'. This instructs
   createusers to copy the quota properties of the user indicated to 
   each new user when the user is created. 

6. Save changes to /etc/createusers.conf.


Testing
-------

A sample users file is provided. To create the sample users, type:

    createusers users.sample

The three users in the users.sample file should be added to the system.


Apache configuration for personal webspace
------------------------------------------

To enable personal webspace in user home directories, edit the Apache 
web server configuration file. On Red Hat systems, the file is:

/etc/httpd/conf/httpd.conf

The Apache configuration file may be in another location or have a different
name if you are using another Linux distribution.

The following httpd.conf entry is required.  This will set
'public_html' as the user's HTML directory, in the user's home directory.

   # UserDir: The name of the directory which is appended onto a user's home
   # directory if a ~user request is received.
   #
   UserDir public_html
   
 
The following httpd.conf entries are recommended. This will enable 
automatic directory indexes, Server Side Includes except EXEC commands, 
following symbolic links within the file space served by Apache, 
and allow password protection of files and directories using the htaccess 
security mechanism.  

The directories in which these options will take effect are the users'
directories:

 /home/[user]/public_html

and

 /home/[user]/[group]/public_html

Find the UserDir section in your httpd.conf file and modify it to
look like this:

   # Control access to UserDir directories.
    
   <Directory "/home/*/public_html">
   Options Indexes IncludesNoExec ExecCGI FollowSymLinks
   AllowOverride AuthConfig
   </Directory>
    
   <Directory "/home/*/*/public_html">
   Options Indexes IncludesNoExec ExecCGI FollowSymLinks
   AllowOverride AuthConfig
   </Directory> 

Remember to restart the Apache server for the changes to take effect.
The command to restart Apache is:

   /etc/rc.d/init.d/httpd restart

This command works on Red Hat systems; it may be slightly different on 
other Linux distributions.


Creating users files the lazy way
---------------------------------

If you are too lazy to make your own passwords for your new users, the
'passgen' program will create them for you. Start with a file containing
firstnames and surnames, like this:

  Fred, Flintstone
  Wilma, Flintstone
  Barney, Rubble  

An example file 'names.sample' is provided here. Use the 'passgen' 
program to create the users file. Example:

  passgen infile mygroup outfile

The output file 'outfile' will contain:

  fred,b9mrV,Fred Flintstone,mygroup
  wilma,3Xz26,Wilma Flintstone,mygroup
  barney,Z5Grd,Barney Rubble,mygroup  

This file can then be put through createusers using the command:

  createusers outfile

Per Ulrik Arntsen (par@hinesna.no) contributed this code. To change 
the length of the generated password, edit /usr/sbin/passgen. 
