POPFile Command Line and Advanced Options

This is where we will describe all the command-line and configuration options that POPFile supports. POPFile has a modular architecture. Most installations use only a subset of the available modules, so some of the entries in this list will not appear on the Advanced page in the POPFile UI (http://127.0.0.1:8080/advanced) or in the configuration file (popfile.cfg). Every time POPFile starts, it checks which modules are installed and automatically discards any entries which no longer apply.

These are the variables that POPFile uses. Some can be modified to suit your needs. Others are used to store information from session to session. Each variable name is followed by a list of possible values, the default value is in bold type set. Many of these variables can be modified by dedicated controls on the Configuration tab in the POPFile UI. The safest thing to do is modify them there. There is usually a good reason for a variable not to have its own control, but they can be modified on the Advanced page or by manually editing popfile.cfg.

The location of the popfile.cfg file is given near the top of the “All POPFile Parameters” list on the Advanced page.

All of the variables listed below can also be set from the command line. To this end, you have to use the following syntax:

perl popfile.pl --set variable=value --set variable2=value2

where 'variable' is the name of the variable you want to set and 'value' is the value you want to give to the variable.

bayes_corpus

(corpus, some_dir)
the name of the subdirectory where POPFile will look for your corpus.

bayes_database

(popfile.db, some file name)
Name of the file that contains the POPFile database (corpus)

bayes_dbauth

bayes_dbconnect

(dbi:SQLite:dbname=$dbname)

bayes_dbuser

bayes_hostname

(the host name of your machine)
in some cases this is needed for a working X-POPFile-Link header.

bayes_localhostname

()
in some cases this is needed to avoid a warning message when clicking the X-POPFile-Link header. Similar to bayes_hostname but for use in Stealth Mode.

bayes_sqlite_journal_mode

(delete, truncate, persist, memory, off)
the journal mode of SQLite database engine. This option is effective when you are using SQLite backend and using DBD::SQLite v1.20 or later. Changing this parameter to 'memory' will make POPFile faster to update its database (adding messages to history, or reclassifying messages to buckets), but if POPFile crashes when it is updating database the database may be corrupted unexpectedly. (added in v1.1.1)
For more information about the journal mode, please see Pragma statements supported by SQLite.

bayes_sqlite_tweaks

(4294967295, some number)
the parameter for tweak SQLite database. (changed in v1.1.1)
This is a bit mask used to control options when you are using the default SQLite database. By default all the options are on (4294967295 is 0xFFFFFFFF in hexadecimal number).
1 (bit 0) = Synchronous flag
Set the synchronous flag to normal. This value was default of SQLite 2.x. For more information about the synchronous flag, please see Pragma statements supported by SQLite.
2 (bit 1) = Backup database
Backup database every hour. The back up file will be stored in the same folder of the original database and its name will be 'popfile.db.backup'.

bayes_subject_mod_left

([, some char/string)
the character or string that POPFile will insert to the subject before the bucket name.

bayes_subject_mod_pos

(1, -1)
the position that POPFile inserts a subject modification. (added in v1.1.1)
bayes_subject_mod_pos = 1
POPFile will inserts a subject modification at the beginning of the subject.

bayes_subject_mod_pos = -1
POPFile will inserts a subject modification at the end the subject.

bayes_subject_mod_right

(], some char/string)
the character or string that POPFile will insert to the subject following the bucket name. see also: Hiding bucket name in subject in Outlook Express

bayes_unclassified_weight

(100, some factor)
this factor determines when a message is marked as unclassified. POPFile must be less than X times more sure that a messages belongs to a given bucket to mark it as unclassified.

bayes_xpl_angle

(0, 1)
If set to 1 then the X-POPFile-Link will have < > around the URL (e.g. X-POPFile-Link: <http://foo.bar>) when set to 0 there are none (e.g. X-POPFile-Link: http://foo.bar)

config_pidcheck_interval

(5)
the interval (in seconds) when POPFile checks the “popfile.pid” file. POPFile will wait ( config_pidcheck_interval * 2 ) seconds if it find the “pidfile.pid” on startup. If you set it 0, POPFile will never check the pid file. This means that POPFile never checks if the other POPFile process is already running. (added in v1.1.0)

config_piddir

(./, some dir)
the relative path to a directory where POPFile will place its “popfile.pid” file when it starts up. The default setting (./) means the file will be stored in the same directory as the configuration file (popfile.cfg).

GLOBAL_debug

(0, 1, 2, 3)
This number determines whether and how POPFile will log debug output. 0: no output, 1: to file, 2: to screen, 3: file and screen. See the Logger Options section for the settings which control the log format and content.

GLOBAL_last_update_check

Stores the date (machine readable) of the last check for updates.

GLOBAL_message_cutoff

(100000)
The maximum size (in bytes) of a message that gets parsed by POPFile. The rest is discarded. A value of 0 denotes no thresshold, i.e. the complete message is parsed regardless of its size.

GLOBAL_msgdir

(messages/, some_dir)
relative path to the directory where POPFile will store the messages used for the history.

GLOBAL_timeout

(60, some number of seconds)
The timeout value for POP3 connections.

GLOBAL_update_check

(0, 1)
Determines whether POPFile should check for updates (1) or not (0).

history_archive

(0, 1)
determines whether messages removed from the history are archived (1) or not (0).

history_archive_classes

This is an advanced setting which will save archived files to a randomly numbered sub-directory, if set to greater than zero, otherwise messages will be saved in the bucket directory (the default setting is 0). 0 ⇐ directory name < archive_classes

history_archive_dir

(archive, some_dir)
the name of the directory where the message archive should be stored.

history_history_days

(2, some number)
number of days to keep messages in the history.

html_cache_templates

(0, 1)
Whether or not the HTML::Template module should cache the templates in memory or not. Caching templates may result in faster performance of the POPFile UI, but it may also result in strange effects when switching skins. If caching is enabled, you should restart POPFile after changing the skin.

html_column_characters

(0, any number)
This is set by the 'Increase' and 'Decrease' column width controls on the history page. The default (0) is automatic width of the history columns.

html_columns

(+inserted,+from,+to,-cc,+subject,-date,-size,+bucket)
Stores information about the columns that should or should not be shown on the history page.

html_date_format

(empty string, some format string)
The format used to display the date for messages on the history page. If the default (an empty string) is used, the format string will be read from the currently set language file. See WorldDomination and DateFormat for more detailed information.

html_language

(English, some other language)
The language POPFile should use for its UI (This is the name (with the .msg extension removed) of a file in the 'languages' directory; e.g. Espanol means the file Espanol.msg will be used)

html_last_reset

Stores the date (in human readable text format) of the last reset of the POPFile statistics.

html_local

(0, 1)
Determines whether POPFile should accept http requests from other machines (0) or not (1).

html_page_size

(20, some number)
The number of messages that are displayed on each page of the history.

html_password

(string of 32 hex chars)
The password for the POPFile UI (encrypted).

html_port

(8080, a port number)
The port used for the http interface to the UI.

html_send_stats

(0, 1)
Determines whether POPFile should send a daily report of accuracy statistics to getpopfile.org (1) or not (0). A daily summary is shown on the Global POPFile Statistics page.

html_session_dividers

(0, 1)
Controls whether session dividers should be shown on the history page or not.

html_show_bucket_help

(0, 1)
Whether to show help on bucket setup on the history and buckets tab or not.

html_show_training_help

(0, 1)
Whether to show help on training on the history and buckets tab or not.

html_skin

(default, name of another skin)
Name of the skin (the directory name) used for the UI.

html_strict_templates

(0, 1)
Whether the template module should die (and make POPFile crash) when the POPFile code sets template variables that are not used in the actual template. Skin authors should set this to 1 to make sure their templates contain all the used variables.

html_test_language

(0, 1)
When set to 1, the UI is switched to a debug mode that enables UI translators to see the strings that they need to find descriptions for in the UI.

html_wordtable_format

(empty, score, prob, freq)
Determines whether to show the word table by default in the single message view. The empty string will make POPFile skip the word table, “score” will show it and default to the display of word scores and decision chart. “prob” will show it and default to the word probabilities and “freq” will show it and default to the word frequencies.

The log file is enabled or disabled using the GLOBAL_debug setting.

logger_format

(default, tabbed, csv)
Defines the output format for the log files. default uses a space to separate the fields, tabbed uses a tab character and csv uses a comma.

logger_loglevel

(0, 1, 2)
Set how detailed the log is. 0 logs critical errors only, 2 logs everything.

logger_logdir

(./)
Name of the directory where the log file is stored. This directory must exist (POPFile will not create it). The default setting (./) means the log file will be stored in the same directory as the configuration file (popfile.cfg).

nntp_enabled

(0, 1)
Enables (1) or disables (0) the NNTP module.

nntp_force_fork

(0, 1)
Fork a child process when the proxy is used (1) or don't (0).

nntp_headtoo

(0, 1)
(added in v1.1.0)
nntp_headtoo = 0
Any HEAD command sent by the news client is simply proxied to the news server. No classification attempt is made, no X-Text-Classification header is inserted and no subject modification is attempted.

nntp_headtoo = 1
In this mode, POPFile internally captures the HEAD command from the news client and replaces it with an ARTICLE command issued to the news server. That causes the entire message to get retrieved. POPFile classifies that message and then DOES insert the XTC and DOES perform Subject modification (if appropriate) before it returns the header of the message to the news client.

Note: setting headtoo to true (1) will mean that every message appears twice in your Popfile History. This will have only a nominal impact though, because the history gets cleared automatically after a few days and overall accuracy should be the same. Either message can be used to reclassify the message within POPFile.

nntp_local

(0, 1)
Allow connections only from local machine (1) or also from remote machines (1).

nntp_port

(119)
Port at which POPFile is listening for nntp connections.

nntp_separator

(:)
Separator character used between login and server strings.

nntp_welcome_string

(NNTP POPFile (v1.1.1) server ready)
The string with which connecting news clients are greeted.

pop3_enabled

(0, 1)
Enable (1) or disable (0) the POP3 module.

pop3_force_fork

(on windows: 0, 1; on other OSs: 0, 1)
Fork off a new child process when the proxy is in use. This enables concurrent connections and will make the UI accessible while the POP3 proxy is doing work. This is currently not recommended on windows.

pop3_local

(0, 1)
Allow remote machines to connect to POPFile's POP3 proxy (0) or restrict use to local connections (1).

pop3_port

(110, some other port)
The port at which POPFile is listening for incoming POP3 connections.

pop3_secure_port

(110, some other port)
The port at which POPFile is listening for incoming secure POP3 connections.

pop3_secure_server

(empty string)

pop3_separator

(:, some character)
Separator character used to split up the login information the client sends to POPFile into host name and port separated by a colon on the one side of the character and the login name on the other side.

pop3_socks_port

(1080, some other port number)

pop3_socks_server

(empty string)

pop3_toptoo

(0, 1)
pop3_toptoo = 0
Any TOP command sent by the mail client is simply proxied to the mail server. No classification attempt is made, no X-Text-Classification header is inserted and no subject modification is attempted. One exception, the 'fetchmail' exception exists. If the TOP command is in the form TOP x 99999999, it is assumed to be issued by fetchmail and it is treated as a RETR.

pop3_toptoo = 1
In this mode, POPFile internally captures the TOP command from the mail client and replaces it with a RETR command issued to the mail client. That causes the entire message to get retrieved. POPFile classifies that message and then DOES insert the XTC and DOES perform Subject modification (if appropriate) before it returns the requested number of lines of the message to the mail client.

Note: setting toptoo to true (1) will mean that every message appears twice in your Popfile History. This will have only a nominal impact though, because the history gets cleared automatically after a few days and overall accuracy should be the same. Either message can be used to reclassify the message within POPFile.

see also:
Toptoo command reference

pop3_welcome_string

(POP3 POPFile (v1.1.1) server ready)
The string with which connecting mail clients are greeted.

smtp_chain_port

(25)

smtp_chain_server

smtp_enabled

(0, 1)

smtp_force_fork

(0, 1)

smtp_local

(0, 1)
Allow only local connections (1) or accept also connections from remote machines (0).

smtp_port

(25)

smtp_welcome_string

(SMTP POPFile (v1.1.1) welcome)
The string with which connecting clients are greeted.

windows_console

(0,1)
When 'runpopfile.exe' or 'popfile.exe' is used to run POPFile, this determines whether POPFile runs invisibly in the background (0) or in a console (DOS box) window (1). This setting can be changed using a button in the WINDOWS section of the Configuration tab in the POPFile UI.

windows_trayicon

(0,1)
When 'runpopfile.exe' or 'popfile.exe' is used to run POPFile, this determines whether the POPFile system tray icon is enabled (1) or disabled (0). This setting can be changed using a button in the WINDOWS section of the Configuration tab in the POPFile UI. The system tray icon can be used to display the POPFile UI or to shutdown POPFile.

xmlrpc_enabled

(0, 1)
Enable (1) or disable (0) the XML-RPC module.

xmlrpc_local

(0,1)
Boolean, true (1) means only accept connections from local machine, false (0) means ok to accept foreign connections.

xmlrpc_port

(8081, some number)
Port that XMLRPC listens on.