================================================================================

==============================
WHAT IS THIS?
================================================================================
==============================
This is the installation of One Click Kick, a *NIX/Linux installer
REQUIREMENTS
******************************************************************************
**********************
* Apache 2.x.x
* PHP 5.3
* Mysql 5.x
* TFTP Server
* ISC DHCP Server 3.x/4.x
OPTIONAL
******************************************************************************
**********************
* PECL NIS/YP PHP extention (ext/pecl_yp) (If you're using NIS)
* NIS server to get ethers data
* LDAP server to get ethers data
================================================================================
==============================
INSTALLATION
================================================================================
==============================
Directory placement and apache configuration
******************************************************************************
**********************
0. Make sure you have the required packages installed
-- CentOS 6/Red Hat 6: -$ yum install httpd php php-cli php-ldap php-mysql php-process mysql-server tf
tp-server dhcp
1. Place the extracted folder to a location outside your web directory, such as
/var/lib/ock.
2a. If you prefer an alias on your existing web-server, please create a config f
ile
based upon the following same apache configuration file: contrib/apache.conf-sam
ple
2b. If you prefer a virtualhost, please create a config file based upon the
following sample apache config file: contrib/apache-virtualhost.conf-sample
3. Make a link from your apache include directory (/etc/httpd/conf.d on a Red
Hat based system, or /etc/apache2/sites-enabled on a Debian based system) to
the configuration file you edited in step 2. Restart the apache web server for
the changes to take effect.
Configure file permissions and the sudoers file
******************************************************************************

**********************
Delete your distribution's original tftpboot directory. (/tftpboot for CentOS/Re
d
Hat/Solaris, and /var/lib/tftpboot for Debian/Ubuntu/etc.)
Create a symbolic link from your distributions default tftpboot folder into
the tftpboot directory provided with OCK. You'll find this directory under the
folder you created in the directory placement section above.
-- CentOS 5/Red Hat 5/Solaris: -# ln -s /var/lib/ock/tftpboot /tftpboot
-- CentOS 6/Red Hat 6: -# ln -s /var/lib/ock/tftpboot /var/lib/tftpboot
-- Debian/Ubuntu: -# ln -s /var/lib/ock/tftpboot /var/lib/tftpboot
Grant read and write permissions for the account running the apache server
to the tftpboot folder. The name of the account varies by distribution and
setup, some examples might be: httpd/www-data/apache/apache.
-- CentOS 5 / Red Hat 5 / Solaris: -# chown -R apache /tftpboot
-- CentOS 6 / Red Hat 6 / Debian / Ubuntu: -# chown -R www-data /var/lib/tftpboot
Grant read and write permissions for the account running the apache server
to the dhcpd.conf file.
-- CentOS 5/Red Hat 5/Solaris: -# chown apache /etc/dhcpd.conf
-- CentOS 6/Red Hat 6: -# chmod 755 /etc/dhcp/.
# chown apache /etc/dhcp/dhcpd.conf
Make sure services start after a reboot:
-- CentOS 6/Red Hat 6: -# chkconfig tftp on
# chkconfig xinetd on; service xinetd start
# chkconfig httpd on; service httpd start
# chkconfig mysqld on; service mysqld start
# chkconfig dhcpd on

Update /etc/sudoers to allow the apache servers account

to restart the DHCP daemon
-- CentOS 5/Red Hat 5/Solaris: -# echo "httpd ALL=(ALL) NOPASSWD: /sbin/service, /etc/init.d/dhcpd, /usr/sbin/dh
cpd, /bin/kill, /bin/rm" >> /etc/sudoers
-- CentOS 6/Red Hat 6: -# echo "apache ALL=(ALL) NOPASSWD: /sbin/service, /etc/init.d/dhcpd, /usr/sbin/d
hcpd, /bin/kill, /bin/rm" >> /etc/sudoers

-- Debian: -# echo "www-data ALL=(ALL) NOPASSWD: /etc/init.d/isc-dhcp-server, /usr/sbin/dhcp

d, /bin/kill, /bin/rm" >> /etc/sudoers
-- Ubuntu: -# echo "www-data ALL=(ALL) NOPASSWD: /etc/init.d/dhcpd3-server, /usr/sbin/dhcpd3
, /bin/kill, /bin/rm" >> /etc/sudoers
-- FreeIPA / Red Hat IDM: -Add the sudo command group:
# ipa sudocmdgroup-add --desc="One Click Kick" oneclickkick
Add the commands to the group. The commands must already be defined in IPA. See
above for the correct command for your distribution:
# ipa sudocmdgroup-add-member oneclickkick --sudocmds="/etc/init.d/dhcpd, /usr/s
bin/dhcpd, /bin/kill, /bin/rm, /sbin/service"
# ipa sudorule-add user-apache-oneclickkick --desc="Apache to run OneClickKick c
mds"
Replace with the hosts running OneClickKick
# ipa sudorule-add-host user-apache-oneclickkick --hosts=ockhostA,ockhostB
# ipa sudorule-add-runasuser user-apache-oneclickkick --users=root
# ipa sudorule-add-user user-apache-oneclickkick --users=apache
# ipa sudorule-add-allow-command user-apache-oneclickkick --sudocmdgroups="onecl
ickkick"
# ipa sudorule-add-option user-apache-oneclickkick --sudooption='!authenticate'
# ipa sudorule-add-option user-apache-oneclickkick --sudooption='!requiretty'
Remeber to comment out the requiretty line in sudoers as well:
"# Defaults
requiretty"
Grant the web installer permissions to create a config file. (Remember to
remove this permission after you have completed the setup.)
# chmod 777 /var/lib/ock/htdocs/conf

Install the NIS client. (This skip can be skipped if you're not planning to us
e NIS)
******************************************************************************
**********************
Install the PECL NIS/YP client. This client is also included under the
ext/pecl_yp directory. See PECL Documentation for installation howto.
Get started...
******************************************************************************
**********************
Create a database and assign permissions, unless you're planning
to use the root account. Go to the website you configured earlier for setup. (ht
tp://yourwebserver/ock)

Remember to make the config safe AFTER the install script has finished:
# chmod -R 755 htdocs/conf
Download and install boot images from http://oneclickkick.sourceforge.net/. Thes
e are installed in under
the "Profiles" tab in the OneClickKick GUI.

================================================================================
==============================
WHAT'S NEXT?
================================================================================
==============================
After reading, press finish in the installer, and log in to the system. The DHCP
server config will be
written and the DHCP server will be started. The default PXE boot file will also
be written at this point.
Walk trough the configuration, starting with the "configuration" tab, then work
your way trough "subnets",
"profiles", "groups" and then start adding hosts under the "hosts" tab. (From ri
ght to left.)
Go to the OneClickKick download site, and download your preferred boot images. T
hese are added under the
"profiles" tab, using the "Add boot image" option.
Creating new boot images is easy. Take a look in the README.txt file for a quick
howto.
If you want to contribute, or provide feedback about your experience with this p
roject, then please contact
me at slie@nixtra.com.

================================================================================
==============================
USING THE OCK DAEMON
================================================================================
==============================
The OCK daemon will keep your name cache up to date and run time consuming
jobs such as generating the dhcp config file and restarting the dhcp daemon.
Enabling the ock built-in cache (Configuration -> Name caching), and using
the OCK daemon will greatly improve the response of the web interface
on sites having more than 100 hosts.
The OCK daemon requires no explicit configuration. The web interface will
send dhcp restart requests to the OCK daemon if a daemon has been seen within
the last 60 seconds. Any name lookups will be read from the cache if they are
within the configured cache time (Configuration -> Name cache timeout). If no da
emon is
running and the name cache is enabled, the cache will be updated while the web
interface is in use.
To start the OCK daemon, go to the sbin directory and start the daemon with
"./ockd start" option. To stop the OCK daemon run "./ockd stop". This allows
you to use the provided script with init:

# ln -s /path/to/ock/sbin/ockd /etc/rc3.d/S99ockd
Several OCK daemons can be run at the same time. The default is to start 1
daemon.
================================================================================
==============================
INTEGRATING WITH RED HAT IDENTITY MANAGEMENT (www.freeipa.org)
================================================================================
==============================
Configure OCK for the LDAP naming service under "Configuration". Use
authenticated or authenticated ssl connectivity. Specify a bind user that has
been granted with "Host Administrators and "Host Enrollment" privileges.
Hosts from IPA will show up in the hosts overview. Click on "modify" to set
the MAC / Ethernet address.
The host modification will add the ieee802Device objectclass and set the macaddr
ess
attribute for the host object being managed.

================================================================================
==============================
CREATING BOOTDISK HOWTO:
================================================================================
==============================
The bootdisks are zip files which contains the boot images (kernels/initrd/etc)
which is served to a client.
Inside each ZIP file, there is a .ockimage file. This is the file that's being r
ead by OCK for names,
description, if the image can handle kickstart files, etc. The file also contain
s the setup of the actual
pxelinux config, trough the BOOT lines. BOOT-x-y where x is sections, and y line
s within the section.
Don't forget about the ; between the item and the value.
A couple of variables which is expanded when the image is uploaded to OCK:
_IMAGE_ = name of folder the image reside within (/img/_IMAGE_/)
_KS_ = expanded to create provide a path to the kickstart script.
_TFTPSERVER_ = expanded to the TFTP serve serving the image. Useful for stuff li
ke DSL which can
load it's filesystem via TFTP.
BootTypeID:
1 - No auto boot (kickstart)
2 - Kickstart
OSID:
+----+------------------+
| id | name
|
+----+------------------+
| 1 | Other
|
| 2 | DOS
|
| 3 | Red Hat
|

| 4 | Fedora
|
| 5 | Debian
|
| 6 | Ubuntu
|
| 7 | CentOS
|
| 8 | Slackware
|
| 9 | Mandriva
|
| 10 | Scientific Linux |
| 11 | Linux Mint
|
| 12 | Solaris
|
| 13 | OpenSolaris
|
| 14 | OpenIndiana
|
| 15 | SUSE
|
| 16 | FreeBSD
|
| 17 | OpenBSD
|
| 18 | PCLinuxOS
|
| 19 | ArchLinux
|
| 20 | Puppy Linux
|
+----+------------------+
The OSID parameter does not serve any purpose beside displaying the distribution
icon at the moment.
I've been thinking about future expansion for stuff such as the Kickstart Genera
tor, which will
need to be modified on a per distribution basis.
README.OCK
******************************************************************************
**********************
The README.OCK file will be presented when a PXE profile based on this boot imag
e is created or modified.
The README.OCK file should be located within the boot image directory. The file
does not require any special
formatting. It will be presented as it is.
================================================================================
==============================
CUSTOMIZED THEMES:
================================================================================
==============================
Creating your own themes for use with OCK is possible, and easy. The SMARTY
(http://www.smarty.net) template system has been used. The templates are
located within the htdocs/templates directory. Every theme requires it's own
directory, and a ".ocktemplate" file containing the name of the template as a te
xt string.
For smarty variables, please see the existing default template. There are 4
files that's interesting, header.tpl and footer.tpl which are being included
from other templates as the common html code above and below. Then there is
text.tlp and table.tpl which are the two templates which the site is built
around.
If you are not familiar with SMARTY templates, take a look at the SMARTY
crash course website (http://www.smarty.net/crashcourse.php).
================================================================================
==============================
KERBEROS AUTHENTICATION INTEGRATION:

================================================================================
==============================
Please see the docs/README.kerberos
================================================================================
==============================
IMPORT OF HOSTS FROM THE DHCPD SYSLOG FILE:
================================================================================
==============================
Please see the docs/README.syslogimport
================================================================================
==============================
ENROLLMENT/IMPORT OF NEW HOSTS USING PXE BOOT:
================================================================================
==============================
Please see the docs/README.pxe-enrollment
================================================================================
==============================
THANKS TO:
================================================================================
==============================
- Jon Hassall - function unlinkRecursive
- Sina Salek (http://sina.salek.ws/en/contact) - function smartCopy
- Jeff Kabanuk - valuable feedback and testing
- Stephen Poley (http://www.xs4all.nl/~sbpoley) js/formval.js - form validation
toolset
================================================================================
==============================
FUTURE:
================================================================================
==============================
- libvirt integration for virtual machine deployment in a click
- gPXE integration
- Samba interface for a clonezilla repository
================================================================================
==============================
CONTACT:
================================================================================
==============================
- Sigbjorn Lie - slie@nixtra.com. One Click Kick developer.
- SF site: http://oneclickkick.sourceforge.net/
Please let me know if you found this product usable and would like to help me de
velop it further.