|REBOL 3 Docs||Guide||Concepts||Functions||Datatypes||Errors|
|TOC < Back Next >||Updated: 14-Feb-2009 Edit History|
By default, security is set to prevent scripts from modifying any of your files or directories.
Security settings use a REBOL dialect, that is, a language within a language. The normal dialect consists of a block of paired values. The first value in the pair specifies what is being secured:
|file||specifies file security.|
|net||specifies network security.|
A file name or directory path allows you to specify security levels for a specific file or directory.
The second value in the pair specifies the level of security. This can be either a security level word or a block of words. The security level words are:
|allow||allow access with no restrictions.|
|ask||ask permission if any restricted access occurs.|
|throw||throw an error if any restricted access occurs.|
|quit||quit this REBOL session if any restricted access occurs.|
For example, to allow all network access, but to quit on any file access:
secure [ net allow ;allows any net access file quit ;any file access will cause the program to quit ]
If a block is used instead of a security level word, it can contain pairs of security levels and access types. This lets you specify a greater level of detail about the security you require. The access types allowed are:
|read||controls read access.|
|write||controls write, delete and rename access.|
|all||controls all access.|
The pairs are processed in the order they appear, with later pairs modifying the effect of earlier pairs. This permits setting one type of access without explicitly setting all others. For example:
secure [ net allow file [ ask all allow read ] ]
The above sets the security level to ask for all operations except for reading which is to be allowed. This technique can also be used for individual files and directories. For example:
secure [ net allow file quit %source/ [ask read] ]
asks if an attempt is made to read the %source directory. Otherwise, it uses the default ('quit).
There is a special case in which the secure function takes a single word argument that must be one of the security access levels. In that case, the security level for all network and file access is set to that level.
The default security level is now:
secure [ net allow file [ ask all allow read ] ]
The secure function now returns the prior security settings before the new settings were made. This is a block with the global network and file settings followed by file or directory settings. The query word can be used to obtain the settings without modifying them.
current-security: secure query
You can modify the current security level by querying the current settings, modifying them, then using the secure function to set the new values.
Lowering the security level produces a change security settings request. The exception is when the REBOL session is running in quiet mode which will, instead, terminate the REBOL session. No query is generated when security levels are raised. Note that the security request now includes an option to allow all access for the remainder of the scripts processing.
When running REBOL from the shell, the -s argument is equivalent to:
and the +s arguments is equivalent to:
You can now follow the --secure argument with one of the security access levels for both network and file access:
rebol --secure throw
There are a number of arguments that can be specified in a shell command line, in a batch script, or in the properties of an icon. To view the arguments and options available for any version of the REBOL language, type usage at the console prompt.
The command line usage is: REBOL <options> <script> <arguments> All fields are optional. Supported options are: --cgi (-c) Check for CGI input --do expr Evaluate expression --help (-?) Display this usage information --nowindow (-w) Do not open a window --noinstall (-i) Do not install (View) --quiet (-q) Don't print banners --reinstall (+i) Force an install (View) --script file Explicitly specify script --secure level Set security level: (allow ask throw quit) --trace (-t) Enable trace mode --uninstall (-u) Uninstall REBOL (View) Other command line options: +q Force not quiet (View) -s No security +s Full security -- args Provide args without script Examples: REBOL script.r REBOL script.r 10:30 firstname.lastname@example.org REBOL script.r --do "verbose: true" REBOL --cgi -s REBOL --cgi --secure throw --script cgi.r "debug: true" REBOL --secure none
Again, the format of the command line is:
REBOL options script arguments
|options||one or more of the program options. See [bad-link:concepts/specifying.txt] Options below for more details.|
|script||the file name of the script you want to run. If the file name contains spaces, it should be typed in quotes.|
|arguments||the arguments passed to the script as a string. These arguments can be accessed from within the script.|
All of the above arguments are optional, and any combination is permitted.
Typically, you run REBOL with the file name of the script that you want it to evaluate. Only one script file is allowed. For example:
If the file name contains spaces, it must be provided in double quotes.
Program options are identifed with a plus (+) or minus (-) before a character or by a double dash (--) before a word. This is a standard practice for specifying program options on most operating systems.
Here are several examples of how options are used.
To run a script with an option, such as the -s option, which evaluates the script with security turned off, type:
REBOL -s script.r
To obtain usage information about REBOL, type:
REBOL -? REBOL --help
To run REBOL without opening a new window (this is done when you need to redirect output to a file or server), type:
REBOL -w REBOL --nowindow
To prevent the printout of startup information which is useful if you are redirecting the output to a file or server, type:
REBOL -q REBOL --quiet
To evaluate a REBOL expression from the command line, type:
REBOL --do "print 1 + 2" REBOL --do "verbose: true" script.r
This lets you evaluate a remote script with a line such as:
REBOL --do "do http://www.rebol.com/speed.r"
To change the security level of REBOL, type:
REBOL -s script.r REBOL --secure none script.r
REBOL -c cgi-script.r REBOL --cgi
Multiple options are also allowed. Multiple single character options can be included together. Multiple full word options must be separated with spaces.
REBOL -cs cgi-script.r REBOL --cgi --secure none cgi-script.r
The above example runs in CGI mode, with security turned off. The shorthand method is required for various web servers that restrict the number of arguments allowed on the command line (such as the Apache server on Linux).
On most systems, it is possible to redirect standard input and output from and to files. The example:
rebol -w script.r > output-file
redirects output to a file. Similarly,
rebol -w script.r < input-file
redirects input from a file.
Everything on the command line that follows the script file name is passed to the script as its argument. This allows you to write scripts that accept arguments directly from the command line. For example, if you start REBOL with the line:
REBOL script.r 10:30 email@example.com
There are two ways to obtain the command line arguments. The first method returns the arguments as a block of REBOL values:
probe system/options/args ["10:30" "firstname.lastname@example.org"]
The second method returns the arguments as a string:
probe system/script/args "10:30 email@example.com"
When REBOL starts, it attempts to load the rebol.r and user.r boot files. These files are optional, but when found, they can be used to set up networking, define common functions, and initialize data used by scripts.
The rebol.r script file holds special functions or extensions to REBOL that are provided as part of the standard distribution. It is suggested that you do not edit this file as it is overwritten with each new release of REBOL.
The user.r script file holds user preferences. You can edit this file and add whatever definitions or data you require.
On multi-user systems, there can be a different user.r for every user. While the user.r file is not part of the distribution, it is automatically generated if it does not exist.
When REBOL starts, it looks for the rebol.r and user.r files first in the home directory and, if not found there, then in the current directory.
To set a HOME directory, you can set an environment variable in the appropriate login or startup script for your system. Note that some systems, such as UNIX or Linux may already do this, so you do not need to.
For example, on Windows NT to set HOME you can add:
to your environment by following these steps:
On Unix systems, you can set the path to REBOL by adding a line like the following in your login shell script or profile:
For some versions of REBOL, the path is stored in a .rebol file that is located in your home directory.
|TOC < Back Next >||REBOL.com - WIP Wiki||Feedback Admin|