1. Utility functions

1.1. sf_loaded

1.2. sf_version

1.3. sf_exec_url

2. Temporary file management

2.1. sf_cleanup

2.2. sf_get_tmp

3. Error handling

3.1. sf_fatal

3.2. sf_unsupported

3.3. sf_error

3.4. sf_warning

4. User interaction

4.1. sf_msg

4.2. sf_trace

4.3. sf_msg1

4.4. sf_msg_section

4.5. sf_banner

4.6. sf_ask

4.7. sf_yn_question

5. File/dir management

5.1. sf_delete

5.2. sf_find_executable

5.3. sf_create_dir

5.4. sf_save

5.5. sf_rename_to_old

5.6. sf_check_copy

5.7. sf_check_block

5.8. sf_contains_block

5.9. sf_chown

5.10. sf_chmod

5.11. sf_check_link

5.12. sf_comment_out

5.13. sf_uncomment

5.14. sf_check_line

6. User/group management

6.1. sf_set_passwd

6.2. sf_set_passwd_aix

6.3. sf_create_group

6.4. sf_delete_group

6.5. sf_user_exists

6.6. sf_delete_user

6.7. sf_create_user

7. OS management

7.1. sf_compute_os_id

7.2. sf_reboot

7.3. sf_shutdown

7.4. sf_poweroff

8. Filesystem/Volume management

8.1. sf_has_dedicated_fs

8.2. sf_get_fs_mnt

8.3. sf_get_fs_size

8.4. sf_set_fs_space

8.5. sf_create_fs

8.6. sf_lv_exists

8.7. sf_vg_exists

8.8. sf_create_lv

8.9. sf_create_vg

8.10. sf_create_lv_fs

9. Service management

9.1. sf_svc_enable

9.2. sf_svc_disable

9.3. sf_svc_install

9.4. sf_svc_uninstall

9.5. sf_svc_is_installed

9.6. sf_svc_start

9.7. sf_svc_stop

9.8. sf_svc_base

9.9. sf_svc_script

10. Network

10.1. sf_domain_part

10.2. sf_host_part

10.3. sf_dns_addr_to_name

10.4. sf_dns_name_to_addr

10.5. sf_primary_ip_address

11. Software management

11.1. sf_soft_exists

11.2. sf_soft_list

11.3. sf_soft_is_installed

11.4. sf_soft_is_upgradeable

11.5. sf_soft_is_up_to_date

11.6. sf_soft_install_upgrade

11.7. sf_soft_uninstall

11.8. sf_soft_remove

11.9. sf_soft_reinstall

11.10. sf_soft_clean_cache

 

---

1 - Utility functions

1.1 - sf_loaded

Checks if the library is already loaded

Of course, if it can run, the library is loaded. So, it always returns 0.

Allows to support the 'official' way to load sysfunc : sf_loaded 2>/dev/null || . sysfunc.sh

Args None Returns Always 0 Displays Nothing

1.2 - sf_version

Displays library version

Args None Returns Always 0 Displays Library version (string)

1.3 - sf_exec_url

Retrieves executable data through an URL and executes it.

Supports any URL accepted by wget.

By default, the 'wget' command is used. If the $WGET environment variable is set, it is used instead (use, for instance, to specify a proxy or an alternate configuration file).

Args $1 Url Returns the return code of the executed program Displays data displayed by the executed program

2 - Temporary file management

2.1 - sf_cleanup

Deletes all temporary files

Args None Returns Always 0 Displays nothing

2.2 - sf_get_tmp

Returns an unused temporary path

The returned path can then be used to create a directory or a file.

Args None Returns Always 0 Displays An unused temporary path

3 - Error handling

3.1 - sf_fatal

Displays an error message and aborts execution

Args $1 message $2 Optional. Exit code. Returns Does not return. Exits with the provided exit code if arg 2 set, with 1 if not. Displays Error and abort messages

3.2 - sf_unsupported

Fatal error on unsupported feature

Call this function when a feature is not available on the current operating system (yet ?)

Args $1 feature name Returns Does not return. Exits with code 2. Displays Error and abort messages

3.3 - sf_error

Displays an error message

If the ERRLOG environment variable is set, it is supposed to contain a path. The error message will be appnded to the file at this path. If the file does not exist, it will be created.

Args $1 Message Returns Always 0 Displays Error message

3.4 - sf_warning

Displays a warning message

Args $1 message Returns Always 0 Displays Warning message

4 - User interaction

4.1 - sf_msg

Displays a message (string)

If the $sf_noexec environment variable is set, prefix the message with '(n)'

Args $1 message Returns Always 0 Displays Message

4.2 - sf_trace

Display trace message

If the $sf_verbose environment variable is set, displays the message. If not, does not display anything.

Args $1 message Returns Always 0 Displays message if verbose mode is active, nothing if not

4.3 - sf_msg1

Displays a message prefixed with spaces

Args $1 message Returns Always 0 Displays message prefixed with spaces

4.4 - sf_msg_section

Displays a 'section' message

This is a message prefixed with a linefeed and some hyphens. To be used as paragraph/section title.

Args $1 message Returns Always 0 Displays Message

4.5 - sf_banner

Displays a 'banner' message

The message is displayed with an horizontal separator line above and below

Args $1 message Returns Always 0 Displays message

4.6 - sf_ask

Ask a question to the user

Due to compatibility problems, don't use 'no newline' echo options anymore.

Args $1 message Returns Always 0 Displays message

4.7 - sf_yn_question

Asks a 'yes/no' question, gets answer, and return yes/no code

Works at least for questions in english, french, and german : Accepts 'Y', 'O', and 'J' for 'yes' (upper or lowercase), and anything different is considered as 'no'

If the $sf_forceyes environment variable is set, the user is not asked and the 'yes' code is returned.

Args $1 Question string Returns 0 for 'yes', 1 for 'no' Displays Question and typed answer if $sf_forceyes not set, nothing if $sf_forceyes is set.

5 - File/dir management

5.1 - sf_delete

Recursively deletes a file or a directory

Returns without error if arg is a non-existent path

Args $1 Path to delete Returns Always 0 Displays Info msg

5.2 - sf_find_executable

Find an executable file

Args $1 Executable name $2 Optional. List of directories to search. If not search, use PATH Returns Always 0 Displays Absolute path if found, nothing if not found

5.3 - sf_create_dir

Creates a directory

If the given path argument corresponds to an already existing file (any type except directory or symbolic link to a directory), the program aborts with a fatal error. If you want to aAlways 0 this (if you want to create the directory, even if somathing else is already existing in this path), call sf_delete first. If the path given as arg contains a symbolic link pointing to an existing directory, it is left as-is.

Args $1 Path $2 Optional. Directory owner[:group]. Default: root $3 Optional. Directory mode in a format accepted by chmod. Default: 755 Returns Always 0 Displays Info msg

5.4 - sf_save

Saves a file

No action if the 'sf_nosave' environment variable is set to a non-empty string. If the input arg is the path of an existing regular file, the file is copied to '$path.orig' TODO: improve save features (multiple numbered saved versions,...)

Args $1 Path Returns Always 0 Displays Info msg

5.5 - sf_rename_to_old

Renames a file to '<dir>/old.<filename>

Args $1 Path Returns Always 0 Displays Info msg

5.6 - sf_check_copy

Copy a file or the content of function's standard input to a target file

The copy takes place only if the source and target files are different. If the target file is already existing, it is saved before being overwritten. If the target path directory does not exist, it is created.

Args $1 Source path. Special value: '-' means that data to copy is read from stdin, allowing to produce dynamic content without a temp file. $2 Target path $3 Optional. File creation mode. Default=644 Returns Always 0 Displays Info msg

5.7 - sf_check_block

Replaces or prepends/appends a data block in a file

The block is composed of entire lines and is surrounded by special comment lines when inserted in the target file. These comment lines identify the data block and allow the function to be called several times on the same target file with different data blocks. The block identifier is the base name of the source path.

If the given block is not present in the target file, it is appended or prepended, depending on the flag argument. If the block is already present in the file (was inserted by a previous run of this function), its content is compared with the new data, and replaced if different. In this case, it is replaced at the exact place where the previous block lied.

If the target file exists, it is saved before being overwritten.

If the target path directory does not exist, it is created.

Args $1 If this arg starts with the '-' char, the data is to be read from stdin and the string after the '-' is the block identifier. If it does not start with '-', it is the path to the source file (containing the data to insert). $2 Target path $3 Optional. Target file mode. Default=644 $4 Optional. Flag. Set to 'prepend' to add data at the beginning of the file. Default mode: Append. Used only if data block is not already present in the file. Can be set to '' (empty string) to mean 'default mode'. $5 Optional. Comment character. This argument, if set, must contain only one character. This character will be used as first char when building the 'identifier' lines surrounding the data block. Default: '#'. Returns Always 0 Displays Info msg

5.8 - sf_contains_block

Checks if a file contains a block inserted by sf_check_block

Args $1 The block identifier or source path $2 File path Returns 0 if the block is in the file, !=0 if not. Displays Nothing

5.9 - sf_chown

Change the owner of a set of files/dirs

Args $1 owner[:group] $2+ List of paths Returns chown status code Displays Nothing

5.10 - sf_chmod

Change the mode of a set of files/dirs

Args $1 mode as accepted by chmod $2+ List of paths Returns chmod status code Displays Nothing

5.11 - sf_check_link

Creates or modifies a symbolic link

The target is saved before being modified. Note: Don't use 'test -h' (not portable) If the target path directory does not exist, it is created.

Args $1 Link target $2 Link path Returns Always 0 Displays Info msg

5.12 - sf_comment_out

Comment one line in a file

The first line containing the (grep) pattern given in argument will be commented out by prefixing it with the comment character. If the pattern is not contained in the file, the file is left unchanged.

Args None Returns Always 0 Displays Info msg

5.13 - sf_uncomment

Uncomment one line in a file

The first commented line containing the (grep) pattern given in argument will be uncommented by removing the comment character. If the pattern is not contained in the file, the file is left unchanged.

Args None Returns Always 0 Displays Info msg

5.14 - sf_check_line

Checks if a given line is contained in a file

Takes a pattern and a string as arguments. The first line matching the pattern is compared with the string. If they are different, the string argument replaces the line in the file. If they are the same, the file is left unchanged. If the pattern is not found, the string arg is appended to the file. If the file does not exist, it is created.

Args $1 File path $2 Pattern to search $3 Line string Returns Always 0 Displays Info msg

6 - User/group management

6.1 - sf_set_passwd

Change a user's password

Works on HP-UX, Solaris, and Linux. Replaces an encrypted passwd in /etc/passwd or /etc/shadow. TODO: Unify with AIX and autodetect the file to use (passwd/shadow)

Args $1 Username $2 Encrypted password $3 File path Returns Always 0 Displays Nothing

6.2 - sf_set_passwd_aix

Set an AIX password

TODO: Unify with other supported OS

Args $1 Username $2 Encrypted password Returns Always 0 Displays nothing

6.3 - sf_create_group

Create a user group

Args None Returns Always 0 Displays Info msg

6.4 - sf_delete_group

Remove a group

Args $1 Group name Returns Status from system command Displays nothing

6.5 - sf_user_exists

Checks if a given user exists on the system

Args $1 User name to check Returns 0 if user exists; != 0 if not Displays nothing

6.6 - sf_delete_user

Remove a user account

Args $1 User name Returns Status from system command Displays nothing

6.7 - sf_create_user

Create a user

To set the login shell, initialize the CREATE_USER_SHELL variable before calling the function. For accounts with no access allowed (blocked accounts), $7, $8, and $9 are not set.

Args None Returns Always 0 Displays Info msg

7 - OS management

7.1 - sf_compute_os_id

Computes and displays a string defining the curent system environment

The displayed string is a combination of the OS name, version, system architecture and may also depend on other parameters like, for instance, the RedHat ES/AS branches. It is an equivalent of the 'channel' concept used by RedHat. I personnally call it 'OS ID' for 'OS IDentifier' and use it in every script where I need a single string to identify the system environment the script is currently running on. If the current system is not recognized, the program aborts. By convention, environments recognized by this function must support the rest of the library. Contributors welcome ! Feel free to enhance this function with additional recognized systems, especially with other Linux distros, and send your patches.

Args None Returns Always 0 Displays OS ID

7.2 - sf_reboot

Shutdown and restart the host

Args None Returns does not return Displays nothing

7.3 - sf_shutdown

Shutdown and halt the host

Args None Returns does not return Displays nothing

7.4 - sf_poweroff

Shutdown and poweroff the host

Args None Returns does not return Displays nothing

8 - Filesystem/Volume management

8.1 - sf_has_dedicated_fs

Checks if a directory is a file system mount point

Args $1 Directory to check Returns 0 if true, !=0 if false Displays nothing

8.2 - sf_get_fs_mnt

Gets the mount point of the filesystem containing a given path

Args $1 Path (must correspond to an existing element) Returns Always 0 Displays The mount directory of the filesystem containing the element

8.3 - sf_get_fs_size

Get the size of the filesystem containing a given path

Args $1 Path (must correspond to an existing element) Returns Always 0 Displays FS size in Mbytes

8.4 - sf_set_fs_space

Extend a file system to a given size

Args $1 A path contained in the file system to extend $2 The new size in Mbytes, or the size to add if prefixed with a '+' Returns Always 0 Displays Info msg

8.5 - sf_create_fs

Create a file system, mount it, and set system configuration to mount it

at system start Refuses existing directory as mount point (security)

Args $1 Mount point $2 device path $3 FS type $4 Optional. Mount point directory owner[:group] Returns 0 if no error, 1 on error Displays Info msg

8.6 - sf_lv_exists

Checks if a given logical volume exists

Args $1 VG name $2 LV name Returns 0 if it exists, 1 if not Displays Nothing

8.7 - sf_vg_exists

Checks if a given volume group exists

Args $1 VG name Returns 0 if it exists, 1 if not Displays Nothing

8.8 - sf_create_lv

Create a logical volume

Args $1 Logical volume name $2 Volume group name $3 Size in Mbytes Returns 0: OK, !=0: Error Displays Info msg

8.9 - sf_create_vg

Create a volume group

Args $1 volume group name $2 PE size (including optional unit, default=Mb) $3 Device path, without the /dev prefix Returns 0: OK, !=0: Error Displays Info msg

8.10 - sf_create_lv_fs

Create a logical volume and a filesystem on it

Combines sf_create_lv and sf_create_fs

Args $1 Mount point (directory) $2 Logical volume name $3 Volume group name $4 File system type $5 Size in Mbytes $6 Optional. Directory owner[:group] Returns 0: OK, !=0: Error Displays Info msg

9 - Service management

9.1 - sf_svc_enable

Enable service start/stop at system boot/shutdown

Args $* Service names Returns Always 0 Displays Info msg

9.2 - sf_svc_disable

Disable service start/stop at system boot/shutdown

Args $* Service names Returns Always 0 Displays Info msg

9.3 - sf_svc_install

Install a service script (script to start/stop a service)

Args $1 Source script $2 Service name Returns Always 0 Displays Info msg

9.4 - sf_svc_uninstall

Uninstall a service script (script to start/stop a service)

Args $1 Service name Returns Always 0 Displays Info msg

9.5 - sf_svc_is_installed

Check if a service script is installed

Args $1 Service name Returns 0 is installed, 1 if not Displays Nothing

9.6 - sf_svc_start

Start a service

Args $1 Service name Returns Return code from script execution Displays Output from service script

9.7 - sf_svc_stop

Stop a service

Args $1 Service name Returns Return code from script execution Displays Output from service script

9.8 - sf_svc_base

Display the base directory of service scripts

Args None Returns Always 0 Displays String

9.9 - sf_svc_script

Display the full path of the script corresponding to a given service

Args $1 Service name Returns Always 0 Displays Script path

10 - Network

10.1 - sf_domain_part

Suppresses the host name part from a FQDN

Displays the input string without the beginning up to and including the first '.'.

Args $1 Input FQDN Returns Always 0 Displays truncated string

10.2 - sf_host_part

Extracts a hostname from an FQDN

Removes everything from the first dot up to the end of the string

Args $1 Input FQDN Returns Always 0 Displays truncated string

10.3 - sf_dns_addr_to_name

Resolves an IP address through the DNS

If the address cannot be resolved, displays nothing

Args $1 IP address $2 Optional. DNS server to ask Returns Always 0 Displays Host name as returned by the DNS or nothing if address could not be resolved.

10.4 - sf_dns_name_to_addr

Resolves a host name through the DNS

If the name cannot be resolved, displays nothing

Args $1 Host name to resolve $2 Optional. DNS server to ask Returns Always 0 Displays IP address as returned by the DNS or nothing if name could not be resolved.

10.5 - sf_primary_ip_address

Get the primary address of the system

This is an arbitrary choice, such as the address assigned to the first network nterface. Feel free to improve !

Args None Returns Always 0 Displays IP address or nothing if no address was found

11 - Software management

11.1 - sf_soft_exists

Check if software exist (installed or available for installation)

Args None Returns 0 if every software exists, !=0 if not Displays Nothing

11.2 - sf_soft_list

List installed software

Returns a sorted list of installed software Linux output: (name-version-release.arch)

Args None Returns Always 0 Displays software list

11.3 - sf_soft_is_installed

Check if software is installed

Args $* software name(s) Returns 0 if every argument software are installed. 1 if at least one of them is not. Displays Nothing

11.4 - sf_soft_is_upgradeable

Check if a newer version of a software is available

Note : if the software is not installed, it is not considered as updateable Note : yum returns 0 if no software are available for update

Args $* software name(s) Returns 0 if at least one of the given software(s) can be updated. Displays Nothing

11.5 - sf_soft_is_up_to_date

Check if the installed version of a software is installed and the latest

version

Args $* software name(s) Returns 0 if every argument software are installed and up to date (for yum) Displays Nothing

11.6 - sf_soft_install_upgrade

Install or upgrade a software

Install or updates a software depending on its presence on the host If the software is up to date, no action.

Args $* software name(s) Returns Always 0 Displays Info msg

11.7 - sf_soft_uninstall

Uninstall a software (including dependencies)

Return without error if the software is not installed

Args $* software name(s) Returns Always 0 Displays Info msg

11.8 - sf_soft_remove

Uninstall a software (ignoring spendencies)

Return without error if the software is not installed

Args $* software name(s) Returns Always 0 Displays Info msg

11.9 - sf_soft_reinstall

Reinstall a software, even at same version

Args $* software name(s) Returns Always 0 Displays Info msg

11.10 - sf_soft_clean_cache

Clean the software installation cache

Args None Returns Always 0 Displays Nothing