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

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

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

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

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

body: "100K"

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Example

enable: true

session.sameSite

Name	session.sameSite
Description	Sets the sameSite property in the cookie.
Synopsis	`sameSite: "Lax
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

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

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

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

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

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

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

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

dir: "./tmp/uploads"

upload.remove

Name	upload.remove
Description	Defines whether the uploaded files should be preserved after the request completes.
Synopsis	`remove: true
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

remove: true