REBOL 3 Concepts: Protocols: Initial Setup

Pending Revision

This document was written for R2 and has yet to be revised for R3.

REBOL networking is built-in. To create scripts that use the network protocols you do not need any special include files or libraries. The only requirement is that you provide the basic information necessary to enable protocols to connect to servers or through firewalls and proxies. For instance, to send an email, the SMTP protocol needs an SMTP server name and a reply email address.

Contents

Basic Network Settings

When you run REBOL the first time, you re prompted for the necessary network settings, which is stored in the user.r file. REBOL uses this file to load the required network settings each time it is started. If a user.r is not created and REBOL cannot find an existing user.r file in its paths, no settings are loaded. See the chapter on [bad-link:concepts/operation.txt] for more information.

To change the network settings, type set-user at the prompt. This runs the same network configuration script that ran when REBOL first started. This script is loaded from the rebol.r file. If that file cannot be found, or if you want to edit the setting directly, you can use a text editor on the user.r file.

Within the user.r file the network settings are found in a block that follows the [bad-link:functions/set-net.txt] function. At a minimum the block should contain two items:

• Your email address for use in the from and reply fields of email and for anonymous FTP login
• Your default server; this is also your primary email server

In addition, you can specify a few other items:

• A different incoming email server (for POP)
• A proxy server (for connecting to the network)
• A proxy port number
• A proxy type (see [bad-link:concepts/proxy.txt] Settings below).

You can also add lines after the [bad-link:functions/set-net.txt] function to configure other protocol values. For instance you can set the timeout values for protocols, set the FTP passive mode, set the HTTP user-agent identifier, set up separate proxies for different protocols, and more.

An example of [bad-link:functions/set-net.txt] is:

set-net [user@domain.dom mail.server.dom]

The first field specifies your email from address, and the second field indicates your default server (notice that it does not need quotes here). For most networks, this is enough and no other settings are necessary (unless you require a proxy). Also your default server is used whenever a specific server is not provided.

In addition, if you use a POP server (for incoming email) that is different from your SMTP server (for outgoing email), you can specify that as well:

set-net [
    user@domain.dom
    mail.server.dom
    pop.server.dom
]

However, if your SMTP and POP servers are the same, then this is not necessary.

Proxy Settings

If you use a proxy or firewall, you can provide the set-net function with your proxy settings. This can include the proxy server name or address, a proxy port number to access the server, and an optional proxy type. For example:

set-net [
    email@addr
    mail.example.com
    pop.example.com
    proxy.example.com
    1080
    socks
]

This example would use a proxy called proxy.example.com on its TCP port 1080 with the socks proxy method. To use a socks4 proxy server, use the word socks4 rather than socks. To use the generic CERN server, use the word generic.

You can also set the proxy to be different machines for different schemes (protocols). Each protocol has its own proxy object where you can set the proxy values for just that scheme. Here is an example of setting a proxy for FTP:

system/schemes/ftp/proxy/host: "proxy2.example.com"

system/schemes/ftp/proxy/port-id: 1080

system/schemes/ftp/proxy/type: 'socks

In this case, only FTP uses a special proxy server. Notice that the machine name must be a string and the proxy type must be a literal word.

Here are two more examples. The first example sets the proxy for HTTP to be the generic (CERN) proxy method:

system/schemes/http/proxy/host: "wp.example.com"

system/schemes/http/proxy/port-id: 8080

system/schemes/http/proxy/type: 'generic

In the above example, all HTTP requests go through a generic proxy on wp.example.com using TCP port 8080.

If you want to disable the proxy settings for a particular scheme, you can set the proxy fields to false.

system/schemes/smtp/proxy/host: false

system/schemes/smtp/proxy/port-id: false

system/schemes/smtp/proxy/type: false

In the above example, all outgoing email does not go through a proxy. The false value prevents even the default proxy from being used. If you set these fields to none!, then the default proxy is used if it is configured.

If you want to bypass the proxy settings for particular machines, such as those on your local network, you can provide a bypass list. Here is a bypass list for the default proxy:

system/schemes/default/proxy/bypass:
    ["host.example.net" "*.example.com"]

Note that the asterisk () and question mark (?) characters can be used for pattern matching. The asterisk () as used in the example above bypasses any machine that ends with example.com.

To set a bypass list for only the HTTP scheme, type:

system/schemes/http/proxy/bypass:
    ["host.example.net" "*.example.com"]

Other Settings

In addition to proxy settings, you can set network timeout values for all of the schemes (in the default) or for specific schemes. For instance, to increase the timeout for all schemes, you can write:

system/schemes/default/timeout: 0:05

This sets the network timeout for 5 minutes.

If you want to increase the timeout just for SMTP, you would write:

system/schemes/smtp/timeout: 0:10

Some schemes have custom fields. For instance, the FTP scheme allows you to set passive mode for all transfers:

system/schemes/ftp/passive: on

FTP passive mode is useful because FTP servers that are set to passive mode do not attempt to connect back through your firewall.

When making HTTP accesses to Web sites, you may want to use a different user-agent field in the HTTP request to get better results on a few sites that detect the browser type:

system/schemes/http/user-agent: "Mozilla/4.0"

Access to Settings

Each time REBOL is started, it reads the user.r file to find its network settings. These settings are made with the [bad-link:functions/set-net.txt] function. Scripts have access to these settings through the system/schemes object.

system/user/email ; used for email from and reply
system/schemes/default/host - your primary server
system/schemes/pop/host - your POP server
system/schemes/default/proxy/host - proxy server
system/schemes/default/proxy/port-id - proxy port
system/schemes/default/proxy/type - proxy type

Below is a function that returns a block containing the network settings in the same order as [bad-link:functions/set-net.txt] accepts them:

get-net: func [][
    reduce [
        system/user/email
        system/schemes/default/host
        system/schemes/pop/host
        system/schemes/default/proxy/host
        system/schemes/default/proxy/port-id
        system/schemes/default/proxy/type
    ]
]

probe get-net