cleanup & doc

proxmox_cloud-init.php

@@ -3,19 +3,49 @@
  * cloudinit script for pfSense on Proxmox VE
  * 
  * The script does a pfSense configuration in that manner:
- * 1. looks for an available cloudinit drive and mount it to /etc/cloudinit
- * 2. compares the cloudinit files on the cloudinit drive by a local copy placed in /etc/cloudinit
+ * 1. look for an available cloudinit drive and mount it to /mnt/cloud
+ * 2. compares the cloudinit files on the cloudinit drive by a local copy placed in /etc/cloud
  *    and ends without changing anything if the files on both location are similar
  * 3. parses the cloudinit YAML files and prepare and set the given values to pfSense config array
  * 4. write the pfSense configuration and reboot the instance
+ * 
  * HowTo install:
  * 1. get a copy of the YAML parse from https://github.com/mustangostang/spyc/ and place it to /usr/local/sbin
  * 2. place a copy of proxmox_cloudinit.php also to /usr/local/sbin
- * HowTo use:
- * 1. attach a cloudinit drive to the pfSense VM
- * 2. create a startupscript
+ * 3. place a startup script in /usr/local/etc/rc.d/
+ * 
+ * Example startup script
+ * ----------------------------------------------------------------------------
+ * #!/bin/sh
+ * # PROVIDE: cloudinit
+ * # REQUIRE: FILESYSTEMS netif syslogd
+ * # BEFORE:  LOGIN
+ * 
+ * . /etc/rc.subr
+ * 
+ * name="cloudinit"
+ * 
+ * start_cmd="${name}_start"
+ * stop_cmd=":"
+ * 
+ * load_rc_config $name
+ * : ${cloudinit_enable:=yes}
+ * : ${cloudinit_msg="Starting CloudInit."}
  * 
- * @version 0.9
+ * cloudinit_start()
+ * {
+ * 	/usr/local/bin/php /usr/local/sbin/proxmox_cloud-init.php
+ * }
+ * 
+ * run_rc_command "$1"
+ * ----------------------------------------------------------------------------
+ * 
+ * HowTo use:
+ * 1. attach a cloudinit cdrom to the pfSense VM an boot
+ * 2. boot twice within 5 minutes to force a change run (don't count the automated reboots)
+ * 3. boot thrice within 5 minutes between each reboot to force a restore to factory defaults (don't count the automated reboots)
+ *  
+ * @version 0.9.1
  * @author Andre Genrich andre.genrich@thurdata.ch
  */
 require_once('Spyc.php');                                                      // yaml parser
@@ -55,12 +85,9 @@ function createDir( $path) {
 /**
  * restoreConfiguration removes all local cloudinit files and starts a reset to factory defaults
  * 
- * @param string $cloudInitLocalPath
- * @param array $cloudInitFiles
- * @param string $cloudInitControl
- * @param string $cloudInitResetControl
  */
-function restoreConfiguration( $cloudInitLocalPath, $cloudInitFiles, $cloudInitControl, $cloudInitResetControl) {
+function restoreConfiguration() {
+	global $cloudInitLocalPath, $cloudInitFiles, $cloudInitControl, $cloudInitResetControl;
 	unlink("$cloudInitLocalPath/$cloudInitControl");
 	unlink("$cloudInitLocalPath/$cloudInitResetControl");
 	foreach ( $cloudInitFiles as $cloudInitFile) {
@@ -74,15 +101,12 @@ function restoreConfiguration( $cloudInitLocalPath, $cloudInitFiles, $cloudInitC
  * 
  * $cloudInitControl contains "init" after a change run -> controlEmergencyRun outs the ciúrrent timestamp into $cloudInitControl
  * 
- * @param string $cloudInitLocalPath
- * @param string $cloudInitControl
- * @param string $cloudInitResetControl
- * 
  * @return int 0 to trigger a skip run
  * @return int 1 to trigger an emergency run (set again all cloudinit settings)
  * @return int 3 to trigger a reset to factory defaults run (reset all cloudinit & pfSense changes)
  */
-function controlEmergencyRun( $cloudInitLocalPath, $cloudInitControl, $cloudInitResetControl) {
+function controlEmergencyRun() {
+	global $cloudInitLocalPath, $cloudInitControl, $cloudInitResetControl;
 	if ((file_get_contents( "$cloudInitLocalPath/$cloudInitControl")) == "init") {
 		file_put_contents( "$cloudInitLocalPath/$cloudInitControl", time());
 		return 0;
@@ -113,13 +137,10 @@ function controlEmergencyRun( $cloudInitLocalPath, $cloudInitControl, $cloudInit
  * update the local copy in case of changes
  * or if the local copy does not exist
  * 
- * @param string $cloudInitMountPoint
- * @param string $cloudInitLocalPath
- * @param array $cloudInitFiles
- * 
  * @return bool true in case of updates, false in case of all is up to date 
  */
-function updateCloudInitFiles( $cloudInitMountPoint, $cloudInitLocalPath, $cloudInitFiles) {
+function updateCloudInitFiles() {
+	global $cloudInitMountPoint, $cloudInitLocalPath, $cloudInitFiles;
 	$cloudInitFileDiff = false;
 	// check for updated config files and update the local copy in case of differs
 	foreach ( $cloudInitFiles as $cloudInitFile ) {
@@ -138,12 +159,10 @@ function updateCloudInitFiles( $cloudInitMountPoint, $cloudInitLocalPath, $cloud
 /**
  * checkCloudInitFiles probes existence of all necessary cloudinit files
  * 
- * @param string $cloudInitMountPoint
- * @param array $cloudInitFiles
- * 
  * @return bool true in case of all files are in place or false if someone missing
  */
-function checkCloudInitFiles( $cloudInitMountPoint, $cloudInitFiles) {
+function checkCloudInitFiles() {
+	global $cloudInitMountPoint, $cloudInitFiles;
 	foreach($cloudInitFiles as $cloudInitFile) {
 		if (!file_exists("$cloudInitMountPoint/$cloudInitFile")) {
 			return false;
@@ -157,12 +176,10 @@ function checkCloudInitFiles( $cloudInitMountPoint, $cloudInitFiles) {
  * probes any attached cd device for existing cloudinit files
  * mounts the drive to /mnt/cloudinit and probes that all neccessary cloudinit files exist
  * 
- * @param string $cloudInitMountPoint
- * @param array $cloudInitFiles
- * 
  * @return bool true in case of success, fals in case of no cloudinit drive could found
  */
-function checkCloudInitDevice( $cloudInitMountPoint, $cloudInitFiles) {
+function checkCloudInitDevice() {
+	global $cloudInitMountPoint, $cloudInitFiles;
 	// get attached cd devices
 	preg_match_all( "/.*cd[0-9] /", file_get_contents('/var/run/dmesg.boot'), $cdDeviceList);
 	if (empty($cdDeviceList[0])) {
@@ -221,13 +238,13 @@ createDir( $cloudInitMountPoint);
 // create local folder for config & control files
 createDir( $cloudInitLocalPath);
 // search and mount the cloudinit image or exit 1
-if (!checkCloudInitDevice( $cloudInitMountPoint, $cloudInitFiles)) {
+if (!checkCloudInitDevice()) {
 	syslog(LOG_ERR,"cloudinit: no cloud init drive available, skipping...\n");
 	exit(1);
 }
 // probe for special run modes
-if (!updateCloudInitFiles( $cloudInitMountPoint, $cloudInitLocalPath, $cloudInitFiles)) {
-	switch (controlEmergencyRun( $cloudInitLocalPath, $cloudInitControl, $cloudInitResetControl)) {
+if (!updateCloudInitFiles()) {
+	switch (controlEmergencyRun()) {
 		case 0:
 			syslog(LOG_INFO,"cloudinit: cloud init files up to date, skipping...\n");
 			exit(0);
@@ -237,7 +254,7 @@ if (!updateCloudInitFiles( $cloudInitMountPoint, $cloudInitLocalPath, $cloudInit
 		break;
 		case 2:
 			syslog(LOG_INFO,"cloudinit: reset run triggered, restore cloudinit default configuration!\n");
-			restoreConfiguration( $cloudInitLocalPath, $cloudInitFiles, $cloudInitControl, $cloudInitResetControl);
+			restoreConfiguration();
 		break;
 	}
 }