Difference between revisions of "Groovix Net Control"

From GroovixWiki
Jump to: navigation, search
 
(32 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
__TOC__
 
__TOC__
  
The Groovix system provides all networked workstations with unified profiles and software updates as part of the Groovix update process. This process is done through a system called Groovix NetCustomization or GNC. It queries updates, fixes and system changes from the [[Groovix Server]] and runs them automatically. If the system has not applied these updates, they are downloaded and installed automatically.  
+
The Groovix system provides all networked workstations with unified profiles and software updates as part of the Groovix update process. This process is done through a system called Groovix Net Control or GNC. It queries updates, fixes and system changes from the [[Groovix Server]] and runs them automatically. If the system has not applied these updates, they are downloaded and installed automatically.  
 
 
Normally, this process is performed on boot up or customized to your specific update schedule; however, this process can be run manually at any time by typing <font class="code">/etc/init.d/groovix-netcustomization start</font> in an [[xterm]] window. Every time Groovix NetCustomization is run, the results of that process are dumped into a log file that can be accessed for reference or troubleshooting located at <font class="code">/var/log/groovix/netcustomization.log</font>.
 
 
 
 
 
== Setting up Groovix Server for GNC ==
 
Coming Soon
 
  
 +
Normally, this process is performed on boot up, or can be customized to a specific update schedule; however, this process can be run manually at any time by typing <font class="code">groovix-net-control</font> in an [[xterm]] window. Every time Groovix Net Control is run, the results of that process are dumped into a log file that can be accessed for reference or troubleshooting located at <font class="code">/var/log/groovix/net-control/gnc.log </font> .
  
 
== GNC Scripts ==
 
== GNC Scripts ==
GNC updates are contained to their own directory <font class="code">/var/www/groovix/gnc/updates/[customer]</font> where [customer] is the name of your Groovix site found in <font class="code">/etc/groovix/version</font>. Each GNC update has a file at the root of the directory called gnc; the gnc file is written in bash script as a series of commands listed in the order they should be run. Groovix provides parameters and commands that customize how and when GNC updates are run and to which workstations run them, these are described in detail below. Each workstation downloads and executes the script individually after downloading it from Open Sense servers or your local Groovix Server. GNC updates that have been downloaded and executed can be found locally on each workstation in the <font class="code">/var/lib/groovix/updates/master.bash</font> file.
+
GNC updates are contained in their own directory in <font class="code">/var/www/groovix/gnc/updates/[customer]</font> where [customer] is the name of your Groovix site (Groovix site information can found in the <font class="code">/etc/groovix/version</font> file). Each GNC update has a file at the root of the directory called gnc; the gnc file is written in bash script as a series of commands listed in the order they should be run. Groovix provides parameters and commands that customize how and when GNC updates are run and which workstations will run them, these are described in more detail below.  
  
The <font class="code">/var/www/groovix/gnc/updates/[customer]</font> directory contains separate directories for the different types, sites, and labels for your deployment. GNC updates that only apply to a specific workstation type (/etc/groovix/type1,2,etc) should be placed in the directory for that type. Updates placed in the <font class="code">/var/www/groovix/gnc/updates/default</font> directory are applied to all workstations.
+
The <font class="code">/var/www/groovix/gnc/updates/[customer]</font> directory contains separate directories for the different types, sites, and labels for your deployment. GNC updates that only apply to a specific workstation type (ex. web, kiosk type) should be placed in the directory for that type (ex. /var/lib/groovix/updates/web/). Updates placed in the <font class="code">/var/www/groovix/gnc/updates/default</font> directory are applied to all workstations.
  
 +
Each workstation downloads and executes the script individually after downloading it from Open Sense servers or your local [[Groovix Server]]. GNC updates that have been downloaded and executed can be found locally on each workstation in the <font class="code">/var/lib/groovix/updates/master.bash</font> file.
  
 
=== Script Structure ===
 
=== Script Structure ===
The directory structure inside each GNC update should be treated like it is the / (root) directory (ex. overwriting the /etc/network/interfaces file, the interfaces file would be put in a /etc/network/ directory instead of just having the interfaces file in the root of the update directory).
+
To have predictable results with the order in which GNC scripts are run, the GNC_ORDER= variable in the gnc file is used.  The order can be a decimal and typically it is a representation of the date and time that you created or updated the gnc, ex. 20160215.162800 for February 15th at 4:28 pm.
  
Each GNC update name follows a formula of a number followed by the description of the update (ex. 0125-gdm-fix). When a Groovix workstation downloads multiple updates, it runs them in sequential order. 0-1000 is reserved for GNC updates that need to be run first, 2000's are run next followed by 9000 for GNC updates that need to be run last. If it is not critical to run an update, begin the update name with the date the update is created starting with the year (ex. 20110101-floppy-fix). Only use the 1000's or 9000's if your GNC update is required to be run before or after all other updates. If an update changes its function over time or is repurposed, add a -1, -2, etc. to the end of the new update name (ex. 0125-gdm-fix-1); this ensures that this update is applied after the older version and that workstations that already have this update, run it again with the latest change(s).
+
When a Groovix workstation downloads multiple updates, it runs them in sequential order. 0-1000 should be reserved for GNC updates that are required to be run before other updates, 2000's should be used for most typical updates that require no specific order of importance, and 9000's should be reserved for GNC updates that need to be run last, or after other updates.  
  
When you are ready to make your own GNC update, run the <font class="code">cp -rp var/www/groovix/gnc/doc/template/ [updatename]</font> command to create a copy of the template where [updatename] is the name of your update; make sure to name the update according to the rules mentioned above for best results.
+
When you create a new gnc with the gnc-new command the GNC_ORDER= will automatically be set.  When you edit a gnc and want the update to be re-applied to machines that have already run it succesfully, run gnc-bump [updatename] to update the GNC_ORDER= variable in the gnc.
  
  
 
=== Script Rules & Formatting ===
 
=== Script Rules & Formatting ===
 
* Each update must have a gnc file in the root of the update directory
 
* Each update must have a gnc file in the root of the update directory
* Update directories are named with a number, followed by the description
+
* Update directories are typically named for what they do and can contain letters, numbers, dashes, and underscores
 
* Update directories named with 0000-1000 are run first
 
* Update directories named with 0000-1000 are run first
 
* Update directories named by date (20110228) run after initial updates
 
* Update directories named by date (20110228) run after initial updates
 
* Update directories named 9000+ are run after all other updates
 
* Update directories named 9000+ are run after all other updates
* If files are included in your update other than gnc, create the directory structure those files will reside in
+
* If files are included in your update other than gnc, create the directory structure those files will reside in, i.e. mkdir -p [updatename]/etc/cups/printers.conf
 
* The first line of the gnc batch script contains the parameters that dictate how the update will be ran
 
* The first line of the gnc batch script contains the parameters that dictate how the update will be ran
  
  
=== GNC Script Parameters ===
+
=== GNC Control Parameters ===
* abort = exits the script if an error occurs so it can be run again. Avoid the abort flag for conditional arguments (like If statements) or use <font class="code">set +e</font> before the conditional and <font class="code">set -e</font> after the conditional in your script.
+
* --run (always|once|disabled) : always means run this each time GNC runs, once means don't run it after it has run succesfully, disabled means never run it
* attemptonce = as soon as it attempts to run the update, it will never run it again.
+
* --abort : exits the script if an error occurs so it can be run again. Avoid the abort flag for scripts with conditional arguments (like If statements) or use set +e before the conditional and set -e after the conditional in your script.
* background = no longer in use.
+
*  
* depends = not available for use at this time. Will run the update when a prior update has been run successfully.
+
* NOTE: all if and not statements are ANDed together - every single condition must be true for the update to run
* onlybuild = runs the script only when building the image
+
* --if-mode (build|install|live|normal)  :  only run this update if we are running in the specified mode 
* onlyinstall = runs the script only during the imaging process
+
* --not-mode (build|install|live|normal) : do not run this update if we are running in the specified mode     
* onlylive = runs the script only when booting from a [http://wiki2.groovix.org/index.php?title=Groovix_Installation_Guide#Groovix_PAC_Live live cd]
+
* --if-group  (site|type|label|id) :  only run this update if the machines site or type or label or id matched the specified group. all of those categories share a single namespace
* runonce = if the result of the script is successful, it never runs again
+
* --not-group  :  do not run this update if the machines site or type or label or id matched the specified group.  all of those categories share a single namespace
* skipbuild = skips running the script when building the image
+
* --if-from  (startup|shutdown|ssh|shell|cmon) : run this update if gnc was started from the specified process
* skipinstall = skips running the script during the imaging process
+
* --not-from  : do not run this update if gnc was started from the specified process
* skiplive = skips running the script if booting from a [http://wiki2.groovix.org/index.php?title=Groovix_Installation_Guide#Groovix_PAC_Live live cd]
+
 +
* --before [YYYYMMDDHHMM] : only run this gnc if the current time is before the specified datetime
 +
* --after [YYYYMMDDHHMM] : only run this gnc if the current time is after the specified datetime 
 +
*
 +
* ADVANCED USAGE:
 +
* --depends [some-other-group/some-other-update] : this update should only be run if the specified update has successfully run
 +
* --overrides [some-other-group/some-other-update] : this update should be run again anytime the specified update is run
 +
* --cache : download and store this script on the hard drive so that even if it is not applicable to run now it can be run later even if there is no network connection
 +
* --rerun : run the entire GNC process again after processing this GNC, useful for gncs that change GNC parameters
 +
* --continue :  skip the rest of the gncs that were set to run in this iteration
 +
* --break : stop running gnc after this update
 +
* --reboot : reboot the computer after completing the entire GNC process, if you want an immediate reboot after this particular update then use the --break parameter as well
 +
* --fail-override ( warning|disabled|skip|success|complete) : no matter what the script returns, process the outcome as specified 
 +
* --background : run this update in the background, like putting an & after a command in a shell, not recommended
 +
 
 +
=== GNC Script Helper Commands ===
 +
* gncget [filename] - gets file and places it in that same location ,
 +
** use --mod 644  to set the file permissions or it will by 700
 +
** use --gunzip for big files, store it as .gz on the server but refer to it with the .gz in the gncget command, it will be automatically unzipped
 +
** use --tgz to get an entire directory at a time, use [dirname].tgz on the server and give the full path to the directory in the gncget command
 +
* groovix-auto-apt-get install - unattended package install with all defaults
 +
* groovix-auto-apt-get remove  - unattended package uninstall
 +
* bashconfset
 +
* pyconfset
  
 +
== GNC Script Examples ==
 +
''Note: Groovix Network Customization scripts all follow the structure, rules, and syntax documented in the Script Structure section above. Please familiarize yourself with this section before continuing on to the GNC script examples as the examples assume this knowledge is known beforehand.''
  
=== GNC Script Commands ===
+
[[GNC Examples]]
* gncget [filename] = gets file and places it in that same location
 
* apt-get-dontask install = unattended package install with all defaults
 
* apt-get-dontask remove  = unattended package uninstall
 
* --mod 644 = allows file to be downloaded from server
 
* --gunzip = will automatically look for .gz extension, download, unzip, and place the files
 
* --tgz = will automatically tar and gzip
 
  
  

Latest revision as of 11:19, 31 March 2020

The Groovix system provides all networked workstations with unified profiles and software updates as part of the Groovix update process. This process is done through a system called Groovix Net Control or GNC. It queries updates, fixes and system changes from the Groovix Server and runs them automatically. If the system has not applied these updates, they are downloaded and installed automatically.

Normally, this process is performed on boot up, or can be customized to a specific update schedule; however, this process can be run manually at any time by typing groovix-net-control in an xterm window. Every time Groovix Net Control is run, the results of that process are dumped into a log file that can be accessed for reference or troubleshooting located at /var/log/groovix/net-control/gnc.log .

GNC Scripts

GNC updates are contained in their own directory in /var/www/groovix/gnc/updates/[customer] where [customer] is the name of your Groovix site (Groovix site information can found in the /etc/groovix/version file). Each GNC update has a file at the root of the directory called gnc; the gnc file is written in bash script as a series of commands listed in the order they should be run. Groovix provides parameters and commands that customize how and when GNC updates are run and which workstations will run them, these are described in more detail below.

The /var/www/groovix/gnc/updates/[customer] directory contains separate directories for the different types, sites, and labels for your deployment. GNC updates that only apply to a specific workstation type (ex. web, kiosk type) should be placed in the directory for that type (ex. /var/lib/groovix/updates/web/). Updates placed in the /var/www/groovix/gnc/updates/default directory are applied to all workstations.

Each workstation downloads and executes the script individually after downloading it from Open Sense servers or your local Groovix Server. GNC updates that have been downloaded and executed can be found locally on each workstation in the /var/lib/groovix/updates/master.bash file.

Script Structure

To have predictable results with the order in which GNC scripts are run, the GNC_ORDER= variable in the gnc file is used. The order can be a decimal and typically it is a representation of the date and time that you created or updated the gnc, ex. 20160215.162800 for February 15th at 4:28 pm.

When a Groovix workstation downloads multiple updates, it runs them in sequential order. 0-1000 should be reserved for GNC updates that are required to be run before other updates, 2000's should be used for most typical updates that require no specific order of importance, and 9000's should be reserved for GNC updates that need to be run last, or after other updates.

When you create a new gnc with the gnc-new command the GNC_ORDER= will automatically be set. When you edit a gnc and want the update to be re-applied to machines that have already run it succesfully, run gnc-bump [updatename] to update the GNC_ORDER= variable in the gnc.


Script Rules & Formatting

  • Each update must have a gnc file in the root of the update directory
  • Update directories are typically named for what they do and can contain letters, numbers, dashes, and underscores
  • Update directories named with 0000-1000 are run first
  • Update directories named by date (20110228) run after initial updates
  • Update directories named 9000+ are run after all other updates
  • If files are included in your update other than gnc, create the directory structure those files will reside in, i.e. mkdir -p [updatename]/etc/cups/printers.conf
  • The first line of the gnc batch script contains the parameters that dictate how the update will be ran


GNC Control Parameters

  • --run (always|once|disabled) : always means run this each time GNC runs, once means don't run it after it has run succesfully, disabled means never run it
  • --abort : exits the script if an error occurs so it can be run again. Avoid the abort flag for scripts with conditional arguments (like If statements) or use set +e before the conditional and set -e after the conditional in your script.
  • NOTE: all if and not statements are ANDed together - every single condition must be true for the update to run
  • --if-mode (build|install|live|normal)  : only run this update if we are running in the specified mode
  • --not-mode (build|install|live|normal) : do not run this update if we are running in the specified mode
  • --if-group (site|type|label|id) : only run this update if the machines site or type or label or id matched the specified group. all of those categories share a single namespace
  • --not-group  : do not run this update if the machines site or type or label or id matched the specified group. all of those categories share a single namespace
  • --if-from (startup|shutdown|ssh|shell|cmon) : run this update if gnc was started from the specified process
  • --not-from  : do not run this update if gnc was started from the specified process
  • --before [YYYYMMDDHHMM] : only run this gnc if the current time is before the specified datetime
  • --after [YYYYMMDDHHMM] : only run this gnc if the current time is after the specified datetime
  • ADVANCED USAGE:
  • --depends [some-other-group/some-other-update] : this update should only be run if the specified update has successfully run
  • --overrides [some-other-group/some-other-update] : this update should be run again anytime the specified update is run
  • --cache : download and store this script on the hard drive so that even if it is not applicable to run now it can be run later even if there is no network connection
  • --rerun : run the entire GNC process again after processing this GNC, useful for gncs that change GNC parameters
  • --continue : skip the rest of the gncs that were set to run in this iteration
  • --break : stop running gnc after this update
  • --reboot : reboot the computer after completing the entire GNC process, if you want an immediate reboot after this particular update then use the --break parameter as well
  • --fail-override ( warning|disabled|skip|success|complete) : no matter what the script returns, process the outcome as specified
  • --background : run this update in the background, like putting an & after a command in a shell, not recommended

GNC Script Helper Commands

  • gncget [filename] - gets file and places it in that same location ,
    • use --mod 644 to set the file permissions or it will by 700
    • use --gunzip for big files, store it as .gz on the server but refer to it with the .gz in the gncget command, it will be automatically unzipped
    • use --tgz to get an entire directory at a time, use [dirname].tgz on the server and give the full path to the directory in the gncget command
  • groovix-auto-apt-get install - unattended package install with all defaults
  • groovix-auto-apt-get remove - unattended package uninstall
  • bashconfset
  • pyconfset

GNC Script Examples

Note: Groovix Network Customization scripts all follow the structure, rules, and syntax documented in the Script Structure section above. Please familiarize yourself with this section before continuing on to the GNC script examples as the examples assume this knowledge is known beforehand.

GNC Examples


See Also