You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 5 Next »

Required OS Module Subroutines

pre_capture

  • Description
    • Configures the OS so that it can be captured by a provisioning module.
    • Configures the OS so that it will successfully boot after the captured image is reloaded on another resource.
    • Adds and configures drivers so that the image will load on other resources.
    • Removes files which should not be saved in the image.
    • Examples of tasks performed by the pre_capture subroutine:
      • Log off users which were created for the imaging reservation and delete the accounts
      • Set root and administrator passwords to standard, known values 
      • Disable and delete page or swap files
      • Delete temp files
      • Copy scripts and utilities to the computer which are required after the computer boots up but before it has network connectivity
      • Copy drivers to the computer
      • Run a generalization or sealing utility such as Sysprep.exe
  • Expected Beginning State
    • Resource is up and accessible
    • Administrator has configured the resource
    • Administrator may or may not have logged out
  • Expected Ending State
    • (Default) Resource is shut down and turned off
    • Image captured of resource can be loaded and booted on other hardware
    • Loaded image will successfully boot up, establish network connectivity, and be accessible by the OS module's post_load() subroutine
  • Called By
    • Provisioning module's capture() subroutine
  • Arguments & Calling Environment
    • Must only be called as an object method of an OS object ($os->pre_capture()) 
    • Optional Argument:
      • Name: end_state
      • Type: hash reference
      • Description:
        • Instructs pre_capture() to leave the resource in a particular state after the subroutine's tasks are complet instead of shutting down the resource.
      • Possible Values:
        • on - Leave the resource on.  Do not shut it down or reboot it.
        • off (Default) - Shut the resource down.
        • reboot - Initiate a reboot and return.
  • Return Values
    • 1
      • All pre_capture tasks completed successfully.
      • Resource was either shut down or left in the state specified by the end_state argument.
      • Provisioning module can proceed to capture the image.
    • 0
      • Resource OS could not be completely prepared to be captured.
      • Provisioning module should not proceed to capture the image.

post_load

  • Description
    • Performs tasks to configure the OS after an image was loaded.
    • Does not configure the resource for a particular reservation.
    • Examples of tasks performed by the post_load subroutine:
      • Make sure OS licensing has been activated
      • Configure services
      • Rename the computer or resource
      • Randomize passwords
      • Configure the firewall
  • Expected Beginning State
    • Resource has been powered on 
    • Resource may or may not be accessible
    • It's expected that the resource will become accessible automatically after it boots and performs any initialization tasks which were preconfigured by the pre_capture subroutine.
  • Expected Ending State
    • Resource has been loaded with an image and the OS was configured so that it is ready to be reserved.
  • Called By
    • Provisioning module's load() subroutine
  • Arguments & Calling Environment
    • Must only be called as an object method of an OS object ($os->post_load()) 
    • No arguments
  • Return Values
    • 1
      • All OS post-load tasks were completed successfully
    • 0
      • All OS post-load tasks could not be completed but the resource became accessible
    • Undefined
      • Resource never became accessible

sanitize

  • Description
    • Reverts the changes made when preparing a resource for a particular reservation.
    • A resource needs to be sanitized if it was successfully reserved for a reservation but not used.
    • The goal of the sanitize subroutine should be to clean up and reconfigure a resource so that it can be provisioned for another reservation without having to be reloaded.
    • An attempt is made to sanitize the resource by reclaim.pm if it determines that the resource was never used for a reservation.  This will occur if a reservation is made, enters the reserved state, but never enters the inuse state.
    • Examples of tasks performed by the sanitize subroutine:
      • Delete user accounts which were created for a reservation
      • Revoke access to the resource which was granted for a reservation
  • Expected Beginning State
  • Expected Ending State 
  • Called By
    • reclaim.pm::process()
    • May be called by the same OS module's pre_capture() subroutine to sanitize the resource after it was reserved and used by the image creator.
  • Arguments & Calling Environment
    • Must only be called as an object method of an OS object ($os->sanitize())
    • No arguments will be passed to sanitize()
  • Return Values
    • 1
      • Sanitization was completely successful
      • Resource is ready to be provisioned and reserved for another reservation
      • Resource does not need to be reloaded
    • 0
      • Sanitization could not be completed
      • Resource needs to be reloaded

reboot

  • Description
    • Performs a complete graceful reboot of the OS.
    • May forcibly log off users if necessary.
    • Waits for the reboot to complete.
    • Returns after the reboot is complete.
  • Expected Beginning State
    • Computer is up and accessible.
    • Users may be logged on to the computer.
  • Expected Ending State
    • Computer has been rebooted.
    • Computer is accessible.
  • Called By
    • May be called by any module which has access to the OS object
  • Arguments & Calling Environment
    • Must only be called as an object method of an OS object ($os->reboot())
    • Argument:
      • Name: timeout
      • Description:
        • Instructs reboot() to wait a maximum number of minutes for the reboot to complete
        • If timeout has been reached and computer has not finished rebooting, 0 should be returned
      • Required: No
      • Default Value: 5 minutes
      • Data Type: integer
      • Possible Values:
        • Any positive integer
  • Return Values
    • 1
      • Reboot completed successfully
      • Computer is accessible
    • 0
      • Reboot was initiated but computer never came back online
      • Timeout was reached
    • Undefined
      • Reboot could not be initiated

shutdown

  • Description
    • Performs a graceful shutdown of the OS.
    • May forcibly log off users if necessary.
    • Waits for the shutdown to complete.
    • Returns after the shutdown is complete and the computer is off.
  • Expected Beginning State
    • Computer is up and accessible.
    • Users may be logged on to the computer.
  • Expected Ending State
    • Computer is off.
  • Called By
    • May be called by any module which has access to the OS object
  • Arguments & Calling Environment
    • Must only be called as an object method of an OS object ($os->reboot())
    • Argument:
      • Name: timeout
      • Description:
        • Instructs shutdown() to wait a maximum number of minutes for the shutdown to complete
        • If timeout has been reached and computer has not finished shutting down, 0 should be returned
      • Required: No
      • Default Value: 5 minutes
      • Data Type: integer
      • Possible Values:
        • Any positive integer
  • Return Values
    • 1
      • Shudown completed successfully
    • 0
      • Shutdown was initiated but computer never shut down
      • Timeout was reached
    • Undefined
      • Shutdown could not be initiated

get_current_image

  • Description
  • Expected Beginning State
  • Expected Ending State
  • Called By
  • Arguments & Calling Environment
  • Return Values
  • No labels