Skip to content

Web Properties

When Ioto starts, the contents of the web.json5 configuration are blended with the ioto.json5 and made available via the ioto->config in-memory JSON tree.

documents

Name documents
Description Directory containing the static file documents to be published for context.
Synopsis documents: "directoryPath"
Notes The documents property defines the directory containing the documents that will be served. All routes share the same documents directory. The directoryPath should not have a trailing slash.

Example

1
documents: "/var/www"

headers

Name headers
Description Define HTTP headers to add to the client response.
Synopsis headers: { "Header-Key": "Header-Value", ... }
Notes The headers property defines one or more HTTP headers that are added to the client response. You should only define unique headers that are not already added by action routines or by the Ioto web server core. Otherwise, your response will have duplicate headers.

Example

1
2
3
4
5
headers: {
    "Content-Security-Policy":   "default-src 'self'",
    "Strict-Transport-Security": "max-age=31536000; includeSubDomains",
    "CrossOrigin":               "origin=* credentials=yes headers=X-CORS-HEADER age=3000",
}

index

Name index
Description Define the default index file to serve for directory requests.
Synopsis index: "filename"
Notes The index property specifies a document to be served when a HTTP request is made for a directory.

If a client requests a directory, but without a trailing "/" in the URI, the client will be redirected to the URI with a trailing "/". When the client then uses that URI, the directory index file will be used for the response.

For example: if an index of "index.html" is specified and a user requests http://www.acme.com/products/, then the document /products/index.html will be returned to the user.

Example

1
index: "index.html"

limits

The Ioto web server supports configuration properties that improve security by limiting the size and scale of incoming requests. This technique is know as "sandboxing" because it creates a limited or safer area in which Ioto executes.

Name limits
Description Collection of limit properties
Synopsis limits: { "Limit-Property": "Limit-Value", ...}
Notes All limit values may be numbers or human-readable strings with unit suffixes. The unit suffixes can be upper or lower case. The supported units are: unlimited, infinite, kb, k, mb, m, gb, g, byte and bytes. Ioto has sensible defaults for these limits if not explicitly specified.

Example

1
2
3
4
5
6
7
limits: {
    body: "100K",
    connections: "100",
    header: "10K",
    sessions: "20",
    upload: "20MB",
},

limits.body

Name limits.body
Description Sets the maximum size of the request body in POST and PUT requests.
Synopsis body: "max-size"
Notes The body limit defines a maximum size for a POST request body data. For embedded applications, it is useful to limit the request body to the expected maximum. This ensures that rogue or malicious requests will not cause the server to allocate unwanted memory to servicing the request. The default limit is 100K.

Example

1
body: "100K"
Notes Security

This directive can be quite useful in certain denial-of-service attacks where the attacker sends large documents of a certain type.

limits.connections

Name limits.connections
Description Defines the maximum number of simultaneous client connections.
Synopsis connections: "value"
Notes The connections limit defines the maximum number of simultaneous client connections to the server. Connections in excess of this count will be rejected. Set to "unlimited" for no limit. This property counts the number of client socket connections. A single browser may open many separate connections (typically up to 6).

Examples

1
connections: "100"

limits.header

Name limits.header
Description Sets the maximum header size of a request.
Synopsis header: "max-size"
Notes The header limit defines a maximum size for the request headers. For embedded applications, it is useful to limit the maximum headers size to ensure that rogue or malicious requests will not cause the agent to allocate unwanted memory for servicing the request. The default limit is 10K.
Security This property can be quite useful in certain denial-of-service attacks where the attacker sends large documents of a certain type.

Example

1
header: "32K"

limits.sessions

Name limits.sessions
Description Sets the maximum number of active client sessions
Synopsis sessions: "max-sessions"
Notes The sessions limit property defines the maximum number of active client sessions that utilize server-side session state storage. Requests in excess of this count will be rejected. Set to "unlimited" for no limit. This property limits the number of client sessions, whereas the "connections" limit will limit the number of simultaneously connected client systems. NOTE: that many browsers can and will initiate multiple requests when requesting a page. These will share the same session state storage.

Examples

1
sessions: "40"

limits.upload

Name limits.upload
Description Maximum size of an uploaded file.
Synopsis upload: "max-size"
Notes The upload limit defines the maximum size of an uploaded file. In embedded applications, it is useful to limit the maximum file upload size to ensure that rogue or malicious requests will not cause the server to allocate unwanted space for uploads. Set to "unlimited" for no limit. If a file larger than the limit is uploaded, Ioto will reject the request and the client will receive an error. The default value is unlimited.
Security This directive can be quite useful in certain denial-of-service attacks where the attacker sends requests with bogus URLs.

Example

1
upload: "20MB"

listen

Name listen
Description IP addresses and ports on which to listing for incoming requests.<
Synopsis listen: [ "http(s)://[IP address:]portNumber", ...]
Notes The Listen directive specifies the IP endpoints on which Ioto will listen for incoming HTTP requests. If you specify only the port number and omit the IP address, Ioto will listen on all network interfaces including the loop-back adaptor. It will listen on both IPv4 and IPv6 if only a portNumber is specified. >To listen on IPv6 endpoints, enclose the IP address in square brackets. For example: Listen [2001:05c0:9168:0000:0000:0000:0000:0001]. To listen on IPv4 endpoints, supply an IPv4 IP address. You may use 0.0.0.0 to listen on all IPv4 interfaces. To listen for TLS requests, use a "https://" prefix.

Example

1
2
3
4
listen: [
    "http://:80",
    "https://:443",
]

mime

Name mime
Description Mime map to map document extensions to mime types.
Synopsis mime: { "ext": "mime-type", ...}
Notes The mime property defines additional mime types to be added to the Ioto mime type table. Mime type properties are indexed by the document file extension with the value of each key set to the corresponding mime type.

Example

1
2
3
4
mime: {
    ".html": "text/html",
    ".ico": "image/vnd.microsoft.icon",
}

name

Name name
Description Define the public hostname by which the server is known
Synopsis name: "hostname.com"
Notes: The name property specifies the preferred, public, fully qualified hostname for the server. If specified, this address will be used when constructing URLs and redirections. The given hostname should be a fully qualified domain name with port number if using a port other than the default port. If a name is not defined, a value will be determined from the listening endpoint that accepted the connection.

Example

1
name: "www.acme.com"

redirect

Name redirect
Description Redirect requests to a new target.
Synopsis redirect: [ { status: code, from: "URL", to: "URL" }, ... ]
Notes The redirect property maps requests from one URL to a new URL.

The status argument may be either 301 for a permanent redirect or 302 for a temporary redirect. The default is 302.

The from property defines a URL portion that must match for the redirect. If the from property is omitted, it will match all URLs.

The to URL defines a URL portion that will be combined with the existing URL. The to URL may be local to the system, in which case it will begin with a "/" character, or it may be on another system, in which case it will begin with "http://" or "https://". In both cases, the user will receive a HTTP redirection response informing them of the new location of the document.

The from and to URLs are of the form:

[http|https][://][hostname][:port][/path][?query][#hash].

Any of the URL components may be present or absent. For example, if only a path is supplied for the to, then the client will be redirected to the new path on the current site.

Example

1
2
3
4
5
6
7
redirect: [
    { status: 302, from: "example.com", to: "new-example.com" },
    { status: 302, from: "http://example.com:80", to: "https://example.com:443" },
    { status: 302, from: "http://example.com", to: "https://new-example.com" },
    { status: 302, from: ":443", to: "https://:4443" },
    { status: 301, from: "/old", to: "/new.html" },
],

route

The Ioto web server responds to requests by selecting a matching request route that describes the processing for the request.

Name route
Description Define a configuration to apply to a set of URLs.
Synopsis routes: [ match: "url-prefix", role: 'ability', ... ]
Notes The routes property specifies an ordered set of routes that defines the required request properties for the request to be accepted.

A route entry has a match property that defines the URL prefix that must match for the route to be used.

The optional methods property specifies the valid HTTP methods for the route. If absent, the GET and POST methods are supported.

The optional "role" property defines a role that the user must possess for the route to be used. If the "role" property is absent, all users will match. If specified, the user must be authenticated first to determine their abilities.

If the route matches, but the user fails to be authorized, the "redirect" property will be used to redirect the user to the given URL.

Ioto tests routes in order and the first matching route is used. If no routes match, the client request is rejected with a 401 status code.

Example

1
2
3
4
5
6
7
8
routes: [
    { match: '/public/' },
    { match: '/auth/' }
    { match: '/members/', role: 'user' }
    { match: '/admin/', role: 'admin' },
    { match: '/trace/', methods: ['OPTIONS', 'TRACE'], trim: '/trace' },
    { redirect: '/auth/login' },
],

route[].match

Name route[].match
Description Define the matching URL to accept the request.
Synopsis match: '/path'
Notes The match property defines the URL for the request to be accepted.

The match defines an exact URL match unless it terminates in a "/" in which case it defines the leading URL prefix. For example, a match of "/directory/" will match all requests that begin with "/directory/", and a match of "/file" will only match URLs equal to "/file".

An empty match or missing match property will cause the route to match all requests. This is useful as a catch-all route.

Example

1
2
3
4
5
6
7
routes: [
    { match: '/public/' },
    { match: '/private.html', role: 'admin' }
    { match: '/members/', role: 'user' }
    { match: '/admin/', role: 'admin' },
    { /* Match all */, role: 'guest' }
],

route[].methods

Name route[].methods
Description Array of supported HTTP method verbs.
Synopsis methods: [ 'GET', 'POST' ]
Notes The methods property defines the set of supported HTTP method verbs for the request to match the route. Any HTTP verb can be specified, however, different request handlers and action routines may only support specific methods. Common HTTP method verbse are: DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT and TRACE.

If the methods property is absent, the default method set of ['GET', 'POST'] is enabled.

WARNING: be careful enabling OPTIONS and TRACE as they have known adverse security implications.

The trim property can be useful to remove a leading portion of the request path.

Example

1
2
3
routes: [
    { match: '/trace/', methods: ['OPTIONS', 'TRACE'], trim: '/trace' },
],

route[].redirect

Name route[].redirect
Description Redirect matching requests that fail authentication
Synopsis redirect: '/auth/login' ]
Notes If the route matches, but the user fails to be authorized, the "redirect" property will be used to redirect the user to the given URL.

Example

1
2
3
routes: [
    { redirect: '/auth/login' }
],

route[].role

Name route[].role
Description Required authentication role
Synopsis role: 'user' ]
Notes The optional "role" property defines a role that the user must possess for the route to be used. If the "role" property is absent, all users will match. If specified, the user must be authenticated first to determine their abilities.

If the route matches, but the user fails to be authorized, the "redirect" property will be used to redirect the user to the given URL.

Call webLogin after authenticating the user's credentials to login the user and define the user's role.

Example

1
2
3
4
5
6
routes: [
    { match: '/public/' },
    { match: '/private.html', role: 'admin' }
    { match: '/members/', role: 'user' }
    { match: '/admin/', role: 'admin' },
],

route[].trim

Name route[].trim
Description Trim a leading portion from the request URL
Synopsis trim: '/prefix' ]
Notes The optional "trim" property defines a leading path segment that will be trimmed from the path before processing the request. This can be useful to define different URL spaces that require different user authentication or processing.

Example

1
2
3
routes: [
    { match: '/trace/', methods: ['OPTIONS', 'TRACE'], trim: '/trace' },
],

sessions

The Ioto web server supports server-side sessions that are indexed by a session cookie. Ioto manages the creation of the session cookie and the management of sessions. APIs to get and set values in session state are provided.

The default session cookie name is -web-session-. You can modify this when building by defining WEB_SESSION_COOKIE to be the cookie name of your choice.

Name session
Description Collection of session properties.
Synopsis sessions: { "Sessions-Property": "Session-Value", ...}

Example

1
2
3
4
5
sessions: {
    cookie: "-web-cookie-",
    enable: true,
    sameSite: "lax",
},

session.cookie

Name session.cookie
Description Controls whether to create session state for a request.
Synopsis enable: true|false

Example

1
enable: true

session.sameSite

Name session.sameSite
Description Sets the sameSite property in the cookie.
Synopsis sameSite: "Lax|None|Strict"
Notes The sameSite property defines the Set-Cookie HTTP header SameSite field. It may be set to "Lax" (the default), "None" or Strict.

See MDN Set-Cookie SameSite for more information.
Security This property is used to effectively defend against CSRF attacks.

Example

1
sameSite: "Lax"

timeouts

The Ioto web server supports timeout properties that improve security by limiting the duration of requests. These timeouts are blended with the timeouts provided via the ioto.json5 timeouts configuration.

Name timeouts
Description Collection of timeout properties.
Synopsis timeouts: { "Timeout-Property": "Timeout-Value", ...}
Notes All timeout values are strings, not numbers.

The string values may take human-readable suffixes which indicate the units for the value. The suffixes can be upper or lower case. The supported units are: infinite, never, sec, secs, seconds, min, mins, minute, minutes, hr, hrs, hour, hours, day, days, week, weeks, month, months, year, years.

Ioto has sensible defaults for these timeouts if not explicitly specified.

Example 

1
2
3
4
5
6
7
timeouts: {
    parse: "10 secs",
    inactivity: "300 secs",
    request: "10 mins",
    session: "30 mins",
    tls: "1 day",
}

timeouts.inactivity

Name timeouts.inactivity
Description Defines the maximum duration of no I/O activity before the request will be terminated.
Synopsis inactivity: "duration"
Notes The inactivity timeout will be triggered if there is no read or write activity on the network connection to the client over the specified timeout period.

Example

1
inactivity: "30 secs"

timeouts.parse

Name timeouts.parse
Description Defines the maximum duration for parsing the request HTTP headers
Synopsis parse: "duration"
Notes The parse timeout will be triggered if Ioto cannot read and parse the HTTP headers over the specified timeout period.

It is a security attack vector to open a connection to a web server and then be very slow, or stall writing the HTTP headers. This consumes a network connection and can lead to a denial of service. Setting the parse timeout to be short will limit this attack.

Example

1
parse: "15 secs"

timeouts.request

Name timeouts.request
Description Defines the maximum duration for a request.
Synopsis request: "duration"
Notes The request timeout will be triggered if the request cannot be completed inside the specified timeout period.

It is good practice to set a request timeout to the maximum duration you expect the longest request to take.

Example

1
request: "2mins"

timeouts.session

Name timeouts.session
Description Defines the maximum duration of session inactivity for preserving session state.
Synopsis session: "duration"
Notes Session state will be preserved for up to the session timeout. When a client accesses or updates the session state, the timeout is restarted.

Example

1
session: "1hr"

upload

Name upload
Description Collection of Upload properties.
Synopsis upload: { "Upload-Property": "Upload-Value", ... }
Notes The Upload properties control requests that use multi-part mime file upload. They control where the files are placed and how long the files are retained.

Example

1
2
3
4
upload: {
    dir: '/tmp',
    remove: true,
}

upload.dir

Name upload.dir
Description Defines the directory to receive uploaded files.
Synopsis dir: "path"
Notes The directory to hold uploaded files should be outside the site "documents" directory.

Example

1
dir: "./tmp/uploads"

upload.remove

Name upload.remove
Description Defines whether the uploaded files should be preserved after the request completes.
Synopsis remove: true | false
Notes The remove property defines whether the uploaded file is removed when the request completes. By default, an action routine that receives the upload file request should process the file before completing. Then Ioto will observe this property to determine if the file should be removed.
Security It is a denial-of-service risk to keep uploaded files in the upload directory after the receiving action routine completes. If the files are not immediately removed, attackers can upload more and more data and exhaust the capacity of the server.

Example

1
remove: true