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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
session.cookie
Name | session.cookie |
---|---|
Description | Controls whether to create session state for a request. |
Synopsis | enable: true|false |
Example
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
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.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
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
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
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
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
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
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