Manipulate Developer Documentation

Manipulate Developer Documentation
V0.23

1) Introduction
2) Variables
2.1 The configuration file
2.2 User Profile
2.3 Other Variables
2.4 Variable Index
3) The Web Update Function
3.1 currentversion - file
3.2 updateinstallscript - file
Documentation Authors

1 Introduction

This documentation is designed to help simplify the development process. It is largely written for my own benefit (Saves me scouring the code wondering what a particular variable does). If you do intend to develop the code, then you may also want to read the User help guide here
If you are intending to write a Third party Module then The Module writing guide will help, though you will still need to refer to this document.
If you are the author of a Third Party software as of version 0.4 it is possible to include a menu entry for your program. Please be aware that users will need to install your software seperately unless you are planning on bundling Manipulate with it.
This documentation will outline what each global variable does. Later I will also add sections for each of the modules.

The users profile is loaded after the configuration file (.config) therefore even if a user was to add ADMIN_USER=Y to the configuration file their user profile would override this.

If you make a changes to this documentation please add yourself to the Documentation Authors section at the end of this document.

Return to Top

2 Variables

The system uses a number of Global Variables. Information about each of these can be found below. This section is split into 4 sections, one for the configuration file, one for the users profile and one for other variables and finally an Index of all the variables used.

Return to Top

2.1 The Configuration File

The Configuration is located in the root directory of the program with the filename .config

Variables

ORG_NAME=

This variable defines the name of the organisation that will be displayed at the top of several menu's, and at the login screen. This variable can be any string. It should be enclosed in quotation marks (" string ")

SORG_NAME=

This variable is for the benefit of the Text To Speech synthesiser. It is intended that the string in ORG_NAME be spelt phonetically, although if the synthesiser has been disabled, or has no problems saying the organisations name then phonetics are not necessary.

SPEECH_SYNTH_ACTIVE=

This variable simply defines whether the Text To Speech synthesiser is activated or not. This needs to be set to either Y or N

SPEECH_SYNTH=

This variable defines the command used to get the Text to Speech Synthesiser to take input from a pipe. The pipe is already in the program. For example on my system I use SPEECH_SYNTH="festival --tts"

LOCAL_ACCOUNTS=

Defines whether manipulate is running on the system that needs to be administered. If this is set to Y then the system will execute all commands locally. If set to N then the system will use SSH to execute the commands on the remote server defined in the next variable.

MACHINE_HOSTNAME=

This defines the hostname of the remote server. It doesn't actually need to be a hostname, it can also be an IP address.

IDENTITY_FILE=

This defines the location of the key needed to log onto the remote system. (i.e. an RSA Key Pair)

BACKUP_DIR=

This defines a local directory to which a removed users home directory should be backed up. This is implemented 1) in case of accidental removal of a user and 2) because information may need to be extracted from it later

REMOTE_BACKUP_DIR=

This does the same as the above variable, but is for systems that are administering a remote system. I decided to implement this as copying a users Home Directory over a network could take a very long time.

WEB_EDITOR=

This defines the default web editor to use. It should be a command i.e. /usr/bin/nano this can be overridden in the users profile

TEXT_EDITOR=

This Defines the default text editor to use. If left blank the system will use the Operating Systems configured default text editor. This can be overridden in the users profile

WEBDOCS_DIR=

Defines the document root of the configured web server.

RDB_LOCATION=

Defines the Remote Database Location. This is only used on systems that are administering a remote system. It allows Administrators to upload and download manipulates User database to the server. Regularly syncing with the server allows manipulate to show more accurate information on the system users (Theoretically)

QUOTA_FS=

Defines the filesystem that Quotas are enabled on.

HTTPD_NAME=
FTPD_NAME=
SSHD_NAME=

These simple defines the names of the daemons running. These are used primarily when restarting services.

APACHE_ROOT=

A badly named variable really. This defines the path to the HTTPD servers configuration file, it does not have to be an Apache configuration file. It was late when I implemented this ;-)

FTP_ROOT=

Defines the path to the FTP Daemons configuration file.

SSH_ROOT=

Defines the path to the SSH Daemons configuration file.

WEB_BROWSER=

Defines the web browser to use. Used primarily in the program for launching the help file

BACKUP_LOCATION=

Defines the path to webserver backups. This is used by the Webserver backup utility and was only recently implemented.

RESTART_COMMAND=

Defines the command used to Restart the server (Whether Local or remote) The reason this is used is on some systems a script is used to complete a few tasks before issuing the restart command.

So there you have it, the Variables from the configuration file (as it currently stands) All simple enough really :-)

Return to Top

2.2 The User Profile

usrname=""

This simply defines the users username. The filename of the users profile should be exactly the same as this

authnum="10001"
checksum="10001"

These two variables are used to ensure that the users profile is not changed from outside the program between the profile being loaded at log in, and subsequent checks. Currently this is not entirely implemented.

ADMIN_USER=Y

Defines whether the user can administer the manipulate system. If not then it must be set to N to prevent a malicious user from trying to override it in the configuration file

ENABLED=Y

Defines whether the user account is enabled.

APACHE_ENABLE=Y
FTP_ENABLE=Y
SSH_ENABLE=Y

Define whether the user is able to administer the HTTP, FTP and SSH services respectively.

USER_ADMINISTRATOR=Y

Defines whether the user is able to administer system users (The operating systems not manipulate)

QUOTA_ADMINISTRATOR=Y

Defines whether the user is able to Administrate Quotas

SYNC_RIGHTS=Y

Defines whether the user is able to sync with the remote server

FRONT_PAGE=Y

Defines whether the user is able to edit HTML documents in the web servers document root

WEB_EDITOR=nano
TEXT_EDITOR=nano

Define the editors the user wishes to use. These override the defaults set in the configuration file. Currently only Admin users can change these.

Return to Top

2.3 Other Variables

VERSION_NUMBER=

This simply tells the system which version is running. This is defined in the file .version This is mainly used by the update module in order to establish whether an update is available.

CURRENT_VERSION=

This is defined in the update file currentversion. It simply tells the updater which version of the system to update to, this is most commonly used to denote which version is stable.

UPDATE_FILE=

This defines the path to the UPDATE_FILE. The system uses wget to fetch this file, the update file is a bash script which uses wget to fetch the updated components and install them. More information can be found here

UPDATE_FILE1=

This defines the filename of the script the web update function should fetch. The variable UPDATE_FILE also contains the filename, this is because they are used at different times. This functionality is intended to be replaced by a far more sane one in the near future ;-)

N=

This is used in the updateinstallscript file and is simply used to define how many updates will be downloaded

SYS_RESTART=

This is used in the updateinstallscript file to define whether the manipulate system will need restarting after the updates are installed (That is the program not the actual system). It is only ever used when an update to the file manipulate is issued.

CONFIG_UPDATE=

This is used in updateinstallscript to define whether or not a configuration file update has been issued. From version 0.3 this is obsolete (pending testing of the new method) and once testing is completed will be removed from the program. Technically this could be used with versions after 0.3 as it doesn't rely on anything within the program, just within the updateinstallscript however the new method is far more convenient for the user

NEW_VERSION=

This is used in updateinstallscript to define the version number that the script fetches. the main purpose for this is for the convenience of developers. It simplifies copying an update install script from a previous version and changing the installation rules. The version number only needs changing in one place using this method.

Return to Top

The Web Update Function

The Update function of the program simply uses wget to fetch the file currentversion from the update server.

Return to Top

3.1 currentversion - file

The file currentversion uses the following Syntax

#!/bin/bash
# File Detailing which updates have been done.
CURRENT_VERSION="0.23"
UPDATE_FILE="http://benscomputer.no-ip.org/manipulate/updates/v0.23/updateinstallscript"
UPDATE_FILE1=updateinstallscript

the variable CURRENT_VERSION is defined here

The Variable UPDATE_FILE points to the update file for the version to which the user will update.It is defined here

UPDATE_FILE1 defines the filename of the update file, this is not normally used at the moment, but it does allow for changing of the filename. Note that the variable UPDATE_FILE also contains the filename.It is defined here

The file currentversion by default fetches a file called updateinstallscript from the update server. The syntax of this file is defined in the next section

Return to Top

3.2 updateinstallscript - file

The updateinstallscript file is the default update file that currentversion fetches from the update server. It uses the following syntax

#!/bin/bash
# Update install script. Contains instructions on downloading and implementing the latest updates.

N=1 #Set this to the number of files that will be downloaded
SYS_RESTART=N #Whether the control module will need restarting afterwards
#CONFIG_UPDATE=N # Obsolete
NEW_VERSION=v0.3 #Set this to the version number the update will fetch
echo "Update beginning"
cd ./.tmp

# Constants - these will always be downloaded
wget $UPDATE_SERVER/$NEW_VERSION/.version
wget $UPDATE_SERVER/$NEw_VERSION/changelog

# Below are the updates that will be downloaded for this update. Once development is less intense all commented lines will be
# removed in order to reduce the bandwidth of update downloads

wget $UPDATE_SERVER/v0.22/.progs/modules/mod_serveradmin
wget $UPDATE_SERVER/$NEW_VERSION/.progs/modules/mod_sambarestart
wget $UPDATE_SERVER/$NEW_VERSION/.progs/modules/mod_smbcontrol
wget $UPDATE_SERVER/$NEW_VERSION/newconfig
echo "Installing Updates"
echo "$N files will be updated"

# Insert installation rules here. Make minor changes first and major ones last. Version number should always be changed last in
# case the update fails part way through

#mkdir ../documentation/HTML/Developer_Docs/
#mv Index.html ../documentation/HTML/Developer_Docs/
chmod 755 mod_*
mv -f mod_* ../.progs/modules/
# mv .config ../config # Obselete
cat newconfig >> ./.config # Adds any new config variables to the configuration file
echo "New configuration variables are available, please see .config for more info"
#mv -f manipulate ../
#mv -f .updateservers ../
#chmod 755 ../manipulate
mv -f .version ../

if [ "$SYS_RESTART" == "Y" ]
then
echo "You will need to restart manipulate for some changes to take effect"
sleep 2
else
echo "Updates installed successfully"
fi

#if [ "$CONFIG_UPDATE" == "Y" ] # Obsolete
#then
#echo "A new configuration file is available, please see the help file for more information"
#sleep 2
#fi

cd ..
rm currentversion
rm updateinstallscript
sleep 4
systemadmin

This script is run, fetched and invoked by the systems update function. As of Version 0.3 the variable CONFIG_UPDATE is obsolete due to a change in the way configuration changes will be made. However this has been left in for two reasons, firstly for historical interest ;-) secondly and more importantly in case testing on the new method does not go as well as hoped.

So far the only reason for the variable SYS_RESTART to be set to Y is when an update is made to the file manipulate. Originally this was every time an update was issued, however the file now holds very little, most of the program lies in modules.

N Actually does very little except display to the user how many files will be downloaded.

NEW_VERSION defines the version of the components to fetch. This means that should someone (perhaps a developer) wish to run an update to an unstable version the script can be invoked from within the program, and overrid currentversion (although this functionality has not been implemented yet)

It is very important that when making changes with the installation rules section, changes that cannot break the functionality of the program are made first. That way if the update should fail, the system should still be usable. The most important thing is to set the Version Number last if the version number is changed first and then the update fails, the system will think there are no updates available.

To run an update the user must have the appropriate privilege enabled in the user profile. The update script has been designed in such a way that it can only be easily run by the system, and not fetched manually and run.

the systemadmin call simply calls the function systemadmin and returns the user to the system administrators menu.

Return to Top

Documentation Authors

Ben Tasker