selectorctl

Navigation:  PHP Selector > Command Line Tools >

selectorctl

Previous pageReturn to chapter overviewNext page

selectorctl is a new tool that replaces cl-selector (which is deprecated and should not be used anymore) and piniset. It is available starting with CageFS 5.1.3.

 

All new features will be implemented as part of selectorctl.

 

Common Options:

 

--interpreter (-i):

chooses the interpreter to work with. Currently only PHP is supported. If omitted,  --interpreter=php is implied.

--version (-v):

specifies alternatives version to work with

--user (-u):

specifies user to take action upon.

--show-native-version (-V):

prints the version of native interpreter

 

Global Options:

 

The global options modify settings in /etc/cl.selector/defaults.cfg file.

 

--list (-l):

lists all available alternatives for an interpreter. For instance on server with Alt-PHP installed, it produces the following output. Columns are: short alternative version, full alternative version and path to php-cgi binary.

 

$ selectorctl --list
5.2 5.2.17 /opt/alt/php52/usr/bin/php-cgi
5.3 5.3.28 /opt/alt/php53/usr/bin/php-cgi
5.4 5.4.23 /opt/alt/php54/usr/bin/php-cgi
5.5 5.5.7 /opt/alt/php55/usr/bin/php-cgi

--summary (-S):

prints alternatives state summary. Output format: alternative version, state ('e' for 'enabled', '-' otherwise), chosen as default one or not ('d' for 'default', '-' otherwise). For example:

 

$ selectorctl --summary
5.2 e -
5.3 e -
5.4 e -
5.5 e -
native e d

 

if used with --show-native-version, displays version for native interpreter:

 

$ selectorctl --summary --show-native-version
5.2 e -
5.3 e -
5.4 e -
5.5 e -
native(5.3) e d

 

--current (-C):

prints currently globally selected default version (it is stored in /etc/cl.selector/defaults.cfg file):

 

$ selectorctl --current
native native /usr/bin/php

                         

If used with --show-native-version, native interpreter version is displayed as well:

 

--current --show-native-version
native(5.3) native(5.3.19) /usr/bin/php

--set-current (-B):

sets specified version as globally default one (in /etc/cl.selector/defaults.cfg file). For example, to set current default version of PHP to 5.4, use:

 

$ selectorctl --set-current=5.4

--disable-alternative (-N):

adds state=disabled option to alternative section. With it a corresponding alternative gets removed from user alternatives selection list. For instance to disable PHP 5.2, run:

 

$ selectorctl --disable-alternative=5.2

--enable-alternative (-Y):

Enables alternative version, removes state=disabled option, if present, from alternative section. For example to enable PHP 5.2:

 

$ selectorctl --enable-alternative=5.2

--enable-extensions (-E):

enables extensions for particular PHP version by adding comma-separated list of extensions of modules for alternative in /etc/cl.selector/defaults.cfg. Requires --version option. For example:

 

$ selectorctl --enable-extensions=pdo,phar --version=5.2

--disable-extensions (-D):

removes extensions for a particular PHP version. Comma-separated list of extensions will be removed from /etc/cl.selector/defaults.cfg. Requires --version. Example:

 

$ selectorctl --disable-extensions=pdo,phar --version=5.2

 

--replace-extensions (-R):

replaces all extensions for particular PHP version to the list of comma separated extensions. Requires --version option. Example:

 

$ selectorctl --replace-extensions=pdo,phar --version=5.2

--list-extensions (-G):

lists extensions for an alternative for a particular version. Requires --version. Example:

 

$ selectorctl --list-extensions --version=5.3
~ xml
- xmlreader
- xmlrpc
- xmlwriter
- xrange
+ xsl

                         

Plus sign (+) stands for 'enabled', minus (–) for 'disabled', tilde (~) means compiled into interpreter. Enabled and disabled state relates to presence in /etc/cl.selector/defaults.cfg file.



 

 

End User Options

 

All end-user settings are contained in individual user's alt_php.ini files and controlled using selectorctl command.

 

--user-summary (-s):

prints user alternatives state summary. Example:

 

$ selectorctl --user-summary --user=user1
5.2 e - -
5.3 e - -
5.4 e - -
5.5 e - -
native e d s

                         

Columns are: alternative version, state ('e' for 'enabled', '-' otherwise), chosen as default one or not('d' for 'default', '-' otherwise), selected as user default one or not ('s' for 'selected', '-' otherwise). If used with --show-native-version, version for native interpreter is shown in parenthesis:

 

$ selectorctl --user-summary --user=user1 --show-native-version
5.2 e - -
5.3 e - -
5.4 e - -
5.5 e - -
native(5.3) e d s

 

--user option is required.

 

-current (-c):

prints currently globally selected default version (in /etc/cl.selector/defaults.cfg file):

 

$ selectorctl --current
5.3 5.3.28 /opt/alt/php53/usr/bin/php-cgi

                         

If used with --show-native-version to display native version:

 

$ selectorctl --user-current --user=user1
5.3 5.3.28 /opt/alt/php53/usr/bin/php-cgiy

 

--user option is required.

--set-user-current (-b):

sets specified version as the one to use for this end user:

 

$ selectorctl --set-user-current=5.4 --user=user1

                         

changes user symlinks for the PHP interpreter to point to alternative 5.4.

                         

--user option is required.

--enable-user-extensions (-e):

Enables comma-separated list of extensions for the user user. Information is saved to alt_php.ini file. Requires --version and --user options.

 

$ selectorctl --enable-user-extensions=pdo,phar --version=5.2 --user=user1

--disable-user-extensions (-d):

Disables extensions provided as comma-separated list. Requires --version and --user options.

 

$ selectorctl --disable-user-extensions=pdo,phar --version=5.2 --user=user1

--replace-user-extensions (-r):

Replaces extensions with a provided comma-separated list of extensions Requires --version and --user options:

 

$ selectorctl --replace-user-extensions=pdo,phar --version=5.2 --user=user1

--reset-user-extensions (-t):

Resets extensions for end user to default list of extensions as defined in default.cfg. Requires --version and --user options.

 

$ selectorctl --reset-user-extensions --version=5.2 --user=user1

--list-user-extensions (-g):

lists enabled user extensions for an alternative. Requires --version and --user options.

 

$ selectorctl --list-user-extensions --version=5.3 --user=user1
xml
xmlreader
xmlrpc

                         

if --all option present, command will list all alternatives extensions marked enabled or disabled for given user. For example:

 

$ selectorctl --list-user-extensions --version=5.3 --user=user1 --all
- xmlreader
- xmlrpc
- xmlwriter
- xrange
+ xsl

                         

Plus sign (+) stands for 'enabled', minus (–) stands for 'disabled'. Enabled and disabled state relates to presence or absence of corresponding extensions in user alt_php.ini file.

--add-options (-k):

adds options (as in php.ini) to user alt_php.ini file. For example:

 

$ selectorctl --add-options=log_errors:on,display_errors:on --version=5.2 --user=user1

                         

adds log_error and display_errors options with values 'on' to user alt_php.ini file overwriting default values for a user. Requires --version and --user options.

--replace-options (-m):

replaces all options in user alt_php.ini file with specified ones. Requires --version and --user options.

 

$ selectorctl --replace-options=log_errors:on,display_errors:on --version=5.2 --user=user1

--delete-options (-x):

removes custom options from user alt_php.ini file. Requires --version and --user options.

 

$ selectorctl --delete-options=log_errors,display_errors --version=5.2 --user=user1

--print-options (-P):

print options from /etc/cl.selector/php.conf file with default values or ones overwritten in user's alt_php.ini file.

 

$ selectorctl --print-options --version=5.2 --user=user1
TITLE:allow_url_fopen
DEFAULT:On
COMMENT:Allows PHP file functions to retrieve data from remote
locations over FTP or HTTP. This option is a great security risk,
thus do not turn it on without necessity.
TYPE:bool
...

                         

Requires --user option. --version option is optional. When --version is omitted, options for current selected version will be printed. By default outputs as plain test. If --json, --csv, --perl is specified, outputs data in corresponding format. For example, with --perl option, the output is perl hash structure that can be evaluated.

 

--reset-options (-z):

removes custom options from alt_php.ini files for ALL users and versions. Backup files in home folders are cleared.

 

$ selectorctl --reset-options        

 

The ranges of affected customers or versions can be narrowed with --version or --user options:

 

$ selectorctl --reset-options --user=user1,user2 --version=5.3,5.4

--list-users (-L):

list users that use particular version of interpreter, specified with --version option. For example, to see all users that use PHP version 5.3:

 

$ selectorctl --list-users --version=5.3

 

--change-to-version (-T):

changes all (or particular user) from one interpreter version to another.

 

$ selectorctl --change-to-version=5.2 --version=5.3

 

Addtional Options:

 

--base64 (-Q)

Sometimes PHP options values can contain commas and other symbols that break command line formatting. In such a case convert a key:value pair into base64 and pass it as value for option-related arguments. For example, to add disable_functions=exec,popen,system and display_errors=on to user options, do the following:

 

$ selectorctl --add-options=`echo disable_functions:exec,popen,system|base64 -w 0`,`echo display_errors:on|base64 -w 0` --version=5.2 --user=user1 --base64

 

Option -w 0 of base64 executable stands for 'disable wrapping of lines'. Without it base64 output will break the command.

 

--quiet

makes selectorctl continue when it encounter option not found in php.conf. Without it selectorctl exits with error.