OldScriptFinder: Documentation: Command Line / Config Options

Table of Contents

Main Options

Any argument not beginning with - (list of directories to scan)

--conf (load a config file)

--emailout (send an email report to the sysadmin)

--emailwarnings (send email warnings to users)

--faster (use the locate program)

--htmlout (generate a HTML report for the sysadmin)

--peruserhtmlout (generate a HTML report for each user)

--peruserxmlout (generate an XML report for each user)

--shutdownnowarning (shutdown scripts without sending warning emails)

--usehttpdconf (only scan directories listed in httpd.conf)

--warningshutdown (disable scripts after a certain number of warnings/amount of time)

--xmlout (generate an XML report for the sysadmin)

Additional Options

• --delhtmlreport
• --delxmlreport
• --*-disable
• --evenhttproot
• --evensuspended
• --exclude
• --finalwarning
• --forceupdates
• --htmlformat
• --httpdconf
• --just
• --justdirs
• --lastmod
• --log
• --logv
• --maxmem
• --maxload
• --moredirs
• --noignores
• --noresold
• --nosymlinks
• --noupdate
• --*-obsolete
• --peruserhtmltemplate
• --reportftp-*
• --sendmail
• --shutdownmethod
• --testemail
• --testmode
• --timeperdir
• --verbosity / -v
• --warningtemplate

Any argument not beginning with -

Arguments not beginning with a - are treated as directories to scan. If directories are passed in this manner, the --usehttpdconf option is ignored. Note that another method for achieving this (which also allows you to specify directories beginning with a -) is the --justdirs option.

Command Line Option

--conf

Specifies the path to a certain config file to use. You may have as many different config files as you wish, for example one which scans and sends out warning emails weekly, another which scans for a specific script daily, and transfers the XML report to a remote server, and a third which performs a monthly scan and disables scripts that have had several warning emails. This option only works on the command line.

Command Line Option

--delhtmlreport

Deletes the HTML report when the scan is finished. This is only really useful if you're using the --reportftp-* options to transfer it to a remote server first, and don't want the copy hanging around on the local server.

Command Line Option

Config File Option

--delxmlreport

Deletes the XML report when the scan is finished. This is only really useful if you're using the --reportftp-* options to transfer it to a remote server first, and don't want the copy hanging around on the local server.

Command Line Option

Config File Option

--*-disable

Disables scanning for a certain script.

Command Line Option

Config File Option

--emailout

Enables the email report. The report is sent to the email address(es) specified in the paramater. Note that this includes all scripts found, so should not normally be sent to end users.

Command Line Option

Config File Option

--emailwarnings

Sends warning emails to users when out of date scripts are detected. The email addresses that warnings are sent to are firstly checked in a file named ".contactemail", in the user's home directory. This is a standard file with the cPanel® control panel, so cPanel® servers should already have this for most users. If the file doesn't exist, the email is addressed directly to the username locally. Owners and home directories are read from /etc/passwd.

See also the --warningtemplate and --warningshutdown options.

Command Line Option

Config File Option

--evenhttproot

By default, when you're using the --usehttpdconf option, Old Script Finder will not disable scripts that are in a root directory listed in httpd.conf. If you wish to disable scripts regardless of if they're in the root directory or not, enable this option. Note that this may result in a user's entire web site being down if they have an old script in their root directory.

Command Line Option

Config File Option

--evensuspended

Only applicable for cPanel® servers. By default, Old Script Finder will not send warning emails out to accounts which are suspended. Enable this option if you want to send warning emails regardless of if the account is suspended or not.

Command Line Option

Config File Option

--exclude

Specifies directories to be excluded from the scan. Note that this is matched with the directory path, so --exclude=/home/sally/ww would exclude directories named "ww", "www", "wwoop", etc, whereas --exclude=/home/sally/ww/ would only exclude "ww".

Command Line Option

Config File Option

--faster

Normally, Old Script Finder manually traverses the directories supplied to it. The --faster option instead uses the locate program to locate potential scripts, then scans the results. For scans with lots of files/directories, this can be significantly faster, but bear in mind that scripts not included since the last time locate updated it's database will not be found, so this option may miss some real scripts.

The speed increase can be significant for large scans, but could actually be slower for very small scans. For example it's normally faster to not use the --faster option when scanning one single directory, as manually traversing the directory is faster than using the locate program.

Command Line Option

Config File Option

--finalwarning

With the --emailwarnings option enabled, this option allows you to send an email which includes a message informing the user that this is their final warning for any scripts which will have more than the specified number of warnings on the next run. For example, passing in this option with the value "3" will add a "This is your final warning about this script" (etc) message to the warning emails for scripts that have had 2 warnings (they'll have 3 warnings on the next scan). No message will be added if the script has been disabled.

The below example sends a standard warning on the first scan, a "This is your final warning" on the second scan, and disables the script on the third scan.

Command Line Option

Config File Option

--forceupdates

Forces Old Script Finder to download all fingerprint and version updates from the server. For example, if you accidentally deleted /var/oldscripts, all of the fingerprint updates will have been wiped out. Running with this option will reinstall them.

Command Line Option

Config File Option

--htmlformat

Prints the standard output in HTML format. Only really useful for the cPanel/WHM Addon, or if you want to run Old Script Finder through a web-based script. If you want a HTML report, instead see --htmlout.

Command Line Option

Config File Option

--htmlout

Enables the HTML report. The parameter should be the path (not the URL) that you wish the report to be written to. This option can contain the special tags <hostname> (which is replaced by the hostname of the server) and <time> (which is replaced by the UNIX timestamp at the time of the scan).

Command Line Option

Config File Option

--httpdconf

The location of httpd.conf, when the --usehttpdconf option is enabled.

Command Line Option

Config File Option

--just

Allows you to specify that only certain scripts should be scanned for.

Command Line Option

Config File Option

--justdirs

A list of directories that should be scanned. Disables the --usehttpdconf option. Note that another way to do this is to simply pass the directories you wish to scan as individual arguments to oldscriptfinder - --justdirs is an alternate method, especially useful when the directory you wish to scan begins with a - character.

Command Line Option

Config File Option

--lastmod

Default is enabled. If enabled, Old Script Finder only scans scripts which have changed since it last scanned them. If disabled, it scans all scripts regardless of if they've changed or not.

Command Line Option

Config File Option

--log

The path to the file to log actions to. If not given, logging is disabled. The log is appended to, rather than wiped each time Old Script Finder runs.

Command Line Option

Config File Option

--logv

The verbosity level for log entries, where 0 is no log entries (except for fatal messages), 1 is the standard output you see when running "oldscriptfinder" on it's own, and 2-7 are increasing levels of verbosity. The default is 2.

Command Line Option

Config File Option

--maxmem

Sets a memory limit for Old Script Finder, in MB. If the memory usage goes above the maxmem setting, Old Script Finder will stop, finish up (write any reports, send warning emails etc), and exit. Note that this may mean that only part of the filesystem is scanned. Also note that Old Script Finder does try to be as frugal as possible with memory, so it should normally not cause a problem. This option is purely for people who want to be sure that it won't breach a certain level.

Command Line Option

Config File Option

--maxload

Note: This option was introduced in Old Script Finder v1.01.

This option specifies a maximum server load that Old Script Finder will run under. If the load goes above the limit specified, Old Script Finder will pause until the load lowers.

Command Line Option

Config File Option

--moredirs

More directories to scan. Does not disable the --usehttpdconf option. This is more useful as a config file option than a command line option.

Command Line Option

Config File Option

--noignores

Normally, users can choose to not receive warnings about a certain script by creating a file named ".oldscriptignore" in the same directory as it. However, with this option enabled, this file is not checked, so users do not have the ability to ignore certain scripts.

Command Line Option

Config File Option

--noresold

Only applicable to cPanel® servers. Enabling this option makes Old Script Finder not send warning emails to accounts owned by resellers.

Command Line Option

Config File Option

--nosymlinks

Normally, Old Script Finder attempts to follow symlinks, and only scan the symlinked directory once. Enabling this option makes Old Script Finder completely ignore any symlinks it encounters.

Command Line Option

Config File Option

--noupdate

Prevents Old Script Finder from downloading fingerprint/version updates.

Command Line Option

Config File Option

--*-obsolete

Allows you to specify that certain scripts are obsolete, and suggest which scripts to replace them with. Note that Old Script Finder already knows about obsolete scripts in general - this is for scripts that aren't actually obsolete but you still consider them so, or you just don't want them on your servers. Obsolete scripts are sent a warning email (as long as --emailwarnings is enabled), and are disabled in the same manner as an old script if the --warningshutdown option is enabled.

Command Line Option

Config File Option

--peruserhtmlout

Generates seperate HTML reports for each user, in seperate files. Each user's report only contains the details for that user's old scripts. A report is not created if there are no old scripts. The parameter is the path to the file that the report should be created as, and can include the special tags <username> (the username for the current user), <time> (the UNIX timestamp at the time of the scan), <hostname> (the hostname of the server) and <homedir> (the path to the user's home directory).

Command Line Option

Config File Option

--peruserhtmltemplate

With the --peruserhtmlout option given, this option allows you to specify the path to a template file for the per-user HTML report. This should be a complete HTML file. Special tags are <version> (the version of Old Script Finder), <numscripts> (the number of scripts being scanned for), <ifwarnings> ... </ifwarnings> (the content (...) is only displayed if there are warnings), <!ifwarnings> ... </!ifwarnings> (the content (...) is only displayed if there aren't warnings) and <foreach> ... </foreach> (which displays the content (...) for each detected script).

Special tags supported within the <foreach> area are <script> (the name of the script found), <dir> (the directory the script is in), <installedversion> (the version of the installed script), <latestversion> (the latest version of the script), <numwarnings> (the number of warnings the user has received about this script), <ifdisabled> ... </ifdisabled> (which displays the content (...) only if the script has been disabled), and <disabledat> (the time the script was disabled).

Command Line Option

Config File Option

Default Per-User HTML Report Template

--peruserxmlout

Generates seperate XML reports for each user, in seperate files. Each user's report only contains the details for that user's old scripts. A report is not created if there are no old scripts. The parameter is the path to the file that the report should be created as, and can include the special tags <username> (the username for the current user), <time> (the UNIX timestamp at the time of the scan), <hostname> (the hostname of the server) and <homedir> (the path to the user's home directory).

If you're using the cPanel® plugin, you'll need to use the filename <homedir>/.oldscriptfinder/report.xml as the per-user XML report when running a full scan.

Command Line Option

Config File Option

--reportftp-*

The --reportftp options allow you to automatically transfer (by FTP) the generated HTML or XML report to a remote server. This is particually useful for the Multi-Server Report tool, which runs on one "master" server, and reads XML reports which have been FTPd to it. The FTP features require the perl module Net::FTP.

--reportftp-html

When the --htmlout option is enabled, transfers the HTML report via FTP to a remote server.

--reportftp-xml

When the --xmlout option is enabled, transfers the XML report via FTP to a remote server.

--reportftp-hostname

The hostname of the remote FTP server.

--reportftp-username

The FTP username to log in to the remote server with.

--reportftp-password

The FTP password to log in with.

--reportftp-cwd

The directory to transfer the report to.

Command Line Option

Config File Option

--sendmail

Specifies the path to the sendmail program. Used when the --emailout and/or --emailwarnings options are enabled. If not supplied, some standard locations are tried.

Command Line Option

Config File Option

--shutdownmethod

If the --warningshutdown option is enabled, this option specifies the method that will be used to disable old scripts which have had too many warnings. Available options are "chmod", which chmods the script's directory to 0000, and "htaccess", which edits the .htaccess file to implement password protection of the directory that the script is in. The default is chmod.

The below example disables old scripts that had their first warning over 3 weeks ago, by adding password protection to the htaccess file.

Command Line Option

Config File Option

--shutdownnowarning

Note: This option was introduced in Old Script Finder v1.03.

Shuts down any scripts detected as old without having to send warning emails. The --emailwarnings option is not essential when this option is enabled - you can have no emails sent at all if you prefer, and still disable the scripts.

Command Line Option

Config File Option

--testemail

When the --emailwarnings option is enabled, this option specifies an email address to send all of the warning emails to. This is useful in testing your warning email template, for example. All of the emails are sent to the address you specify, rather than to the end users. The figures for number of warnings in reports is not incremented with this option specified.

Command Line Option

Config File Option

--testmode

Works through a scan as normal, but does not write a HTML/XML report, send an email report, send email warnings or shutdown scripts.

Command Line Option

Config File Option

--timeperdir

Specifies the maximum amount of time, in minutes, that Old Script Finder will spend scanning each toplevel directory and it's subdirectories. In the below example, Old Script Finder will spend a maximum of 5 minutes scanning /home/mary/www, and a maximum of 5 minutes scanning /home/wesley/www, for a maximum of about 10 minutes. If you use the usehttpdconf option, each directory listed in httpd.conf counts as a toplevel directory, so has a 5 minute maximum to itself.

Command Line Option

Config File Option

--usehttpdconf

Reads Apache's httpd.conf file, and only scans directories that are configured with the DocumentRoot option (and their subdirectories), unless you specify a specific path to scan on the command line. Note that if you enable this option, you also need to pass in or set the --httpdconf option too, to tell Old Script Finder where httpd.conf is.

Command Line Option

Config File Option

--verbosity / -v

Controls how verbose the terminal output of Old Script Finder is, where 0 is no output (except for fatal messages), 1 is the standard output you see when running "oldscriptfinder" on it's own, and 2-7 are increasing levels of verbosity. The default is 1.

Command Line Option

Config File Option

--warningshutdown

This option enables shutdown (disabling) of scripts after the user has received a certain number of warning emails. For example, setting this option to 3 would disable a script when the user has received 2 previous warning emails. Alternatively, you can specify an amount of time since the first warning email was sent about each script. If you just specify a number (for example, 1, 3, 5, 100), it's the number of previous warning emails. If you specify an amount of time (for example, 3w (3 weeks), 3w2d4h, 2Y etc), it's the amount of time since the first warning about that script.

If specifying a time, rather than a number of previous warnings, valid time arguments are Y (years), M (months), w (weeks), d (days), h (hours), m (minutes) and s (seconds). Times can be combined, for example --warningshutdown=2w3d1h15m5s (scripts which received their first warning over 2 weeks, 3 days, 1 hour, 15 minutes and 5 seconds ago will be disabled).

See also the --shutdownmethod option.

Command Line Option

Config File Option

--warningtemplate

Specifies the path to a template for the warning emails, when --emailwarnings is enabled. Special tags are <email> (the email address of the user), <username> (the username) and <foreach> ... </foreach> (the content inside (...) is replicated for each old script in the user's account - they just receive one email with all of their scripts listed).

Within the <foreach> content, special tags are <script> (the name of the script detected), <dir> (the directory the script is in), <installedversion> (the version of the script that the user has installed), <latestversion> (the latest version known to Old Script Finder), <homedir> (the user's home directory), <ifshutdown> ... </ifshutdown> (the content (...) is only included if the script has just been shutdown (disabled), <ifalreadyshutdown> ... </ifalreadyshutdown> (the content (...) is only included if the script was shutdown (disabled) previously), <ifobsolete> ... </ifobsolete> (the content (...) is only included if the script is obsolete, and within <ifobsolete>, <replacement> (the script that is the recommended replacement for the obsolete script, if there is a recommendation) and <ifreplacement> ... </ifreplacement> (the content (...) is only displayed if there is a suggested replacement for the script).

Within the <ifshutdown> ... </ifshutdown> content, special tags are <shutdownusername> (the username to access the directory), <shutdownpassword> (the password to access the directory), and <ifshutdownhtaccess> ... <ifshutdownhtaccess> (the content (...) is only displayed if the shutdown method is 'htaccess'). The former two options are only available if the shutdown method (--shutdownmethod) is 'htaccess'.

Additionally, supported are <iffinal> ... </iffinal> (the content (...) is only displayed if this is the final warning, with --finalwarning), <ifwhenshutdown> ... </ifwhenshutdown> (the content (...) is only displayed if there is a time period configured for the script to be disabled (with --warningshutdown=3w, for example)), and <whenshutdown> (the date that the script will be disabled if no action is taken, again with --warningshutown)

Command Line Option

Config File Option

Default Warning Template

--xmlout

Enables the XML report. The parameter should be the path (not the URL) that you wish the report to be written to. This option can contain the special tags <hostname> (which is replaced by the hostname of the server) and <time> (which is replaced by the UNIX timestamp at the time of the scan). Also see the --reportftp options if you're interested in the multi-server report tool (to see reports from all your servers in one place, parsed and displayed nicely).

Command Line Option

Config File Option