The File Server HTTP Servlet Extension may be used to serve arbitrary files to HTTP clients, including images, HTML files, and other static content located in a specified location on the Directory Server filesystem.
When a request is received, the portion of the request URL up to and including this base context path will be removed and replaced with the path specified in the document-root-directory property in order to determine the path to the corresponding file on the local filesystem.
For example, if the configured base-context-path is "/files", the configured document-root-directory is "/www/files/htdocs", and a client requests "http://server.example.com/files/index.html", the "http://server.example.com/files" portion of the URL will be removed and replaced with "/www/files/htdocs" so that the actual file to be served will be "/www/files/htdocs/index.html".
The File Server HTTP Servlet Extension component inherits from the HTTP Servlet Extension
The following components have a direct aggregation relation from File Server HTTP Servlet Extensions:
The properties supported by this managed object are as follows:
| Description | A description for this HTTP Servlet Extension |
| Default Value | None |
| Allowed Values | A string |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | The cross-origin request policy to use for the HTTP Servlet Extension. A cross-origin policy is a group of attributes defining the level of cross-origin request supported by the HTTP Servlet Extension. |
| Default Value | No cross-origin policy is defined and no CORS headers are recognized or returned. |
| Allowed Values | The DN of any HTTP Servlet Cross Origin Policy. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies HTTP header fields and values added to response headers for all requests. Values specified here must specify both the header field name and the value in conformance with RFC 2616. Fields may only be specified once; multiple values for the same header should be comma-separated. See RFC 7231 for a standard set of field names. Any response headers configured for this HTTP Servlet Extension will be combined with response headers configured on the corresponding Connection Handler. In the case of duplicates, the headers configured on this HTTP Servlet Extension will be used instead of the headers configured on the Connection Handler. |
| Default Value | None |
| Allowed Values | Colon-separated header field name and value |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | HTTP Connection Handlers hosting this HTTP Servlet Extension must be disabled and then re-enabled, or the server restarted, in order for this change to take effect. |
correlation-id-response-header
| Description | Specifies the name of the HTTP response header that will contain a correlation ID value. Example values are "Correlation-Id", "X-Amzn-Trace-Id", and "X-Request-Id". This property can be used to specify a custom response header name for correlation IDs. The value specified here will override the correlation-id-response-header property of the HTTP Connection Handler hosting this HTTP Servlet Extension. If the use-correlation-id-header property of the HTTP Connection Handler hosting this HTTP Servlet Extension is not enabled, then this property will be ignored. |
| Default Value | The correlation-id-response-header property of the HTTP Connection Handler hosting this HTTP Servlet Extension will be used. |
| Allowed Values | A string |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies the base context path that should be used by HTTP clients to reference content. The value must start with a forward slash and must represent a valid HTTP context path. |
| Default Value | None |
| Allowed Values | The value must start with a forward slash and must represent a valid HTTP context path. |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | The File Server HTTP Servlet Extension must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
| Description | Specifies the path to the directory on the local filesystem containing the files to be served by this File Server HTTP Servlet Extension. The path must exist, and it must be a directory. |
| Default Value | None |
| Allowed Values | A filesystem path |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Description | Indicates whether to generate a default HTML page with a listing of available files if the requested path refers to a directory rather than a file, and that directory does not contain an index file. If the value is true, then a generated HTML page will be returned for a request targeting a directory with no index file. If the value is false, then an error response will be returned for such requests. |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies the name of a file whose contents may be returned to the client if the requested path refers to a directory rather than a file. If multiple values are specified, then values will be tried in the order in which they are listing. For example, if index files of "index.html" and "index.htm" are specified (in that order), and the directory targeted by the request contains both index.html and index.htm files, then the content of the index.html file will be returned. If the target directory does not contain index.html but does have index.htm, then the content of the index.htm file will be returned. If a targeted directory does not contain any of the files specified as index files, then the enable-directory-indexing property will be used to determine whether to generate a default HTML page listing the files in that directory, or to return an error response. |
| Default Value | index.html index.htm |
| Allowed Values | A string |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies the path to a file that contains MIME type mappings that will be used to determine the appropriate value to return for the Content-Type header based on the extension of the requested file. If a MIME types file is specified, then it may take one of two forms. It may either use the de-facto standard form in which the MIME type is followed by one or more spaces or tabs, which are then followed by a list of space and/or tab-delimited file extensions (e.g., "text/html html htm" indicates that any file with an extension of "html" or "htm" should have a Content-Type value of "text/html"), or it may use a Java properties file format in which an extension should be followed by an equal sign and the MIME type for that extension (e.g., "html=text/html" indicates that a Content-Type value of "text/html" should be used for files with an extension of "html". Note that even if the properties file format is used, line wrapping is not supported so each definition must be given on one line. |
| Default Value | A default set of MIME type definitions will be used. |
| Allowed Values | A filesystem path |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies the default MIME type to use for the Content-Type header when a mapping cannot be found. |
| Default Value | application/octet-stream |
| Allowed Values | The value must represent a valid Internet media type consisting of a type, subtype and optional parameters. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Indicates whether the servlet extension should only accept requests from authenticated clients. If authentication is required, then the servlet extension will reject any request from a client that does not present authentication credentials. If the require-file-servlet-access-privilege property is set to true, then only users who have the file-servlet-access privilege will be allowed. If the require-group property is defined, then only members of one of the configured groups will be allowed; otherwise, any authenticated client will be granted access. |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | The types of authentication that may be used to authenticate to the file servlet. |
| Default Value | basic access-token id-token |
| Allowed Values | basic - Indicates that basic authentication may be used to provide a username and password. If the username can be parsed as a DN, then that DN will be used to identify the target user. Otherwise, the configured identity mapper (if any) will be used to map that username to a local entry. access-token - Indicates that bearer token authentication may be used to provide an OAuth 2.0 access token. The access token will be validated and mapped to a local user with an access token validator. id-token - Indicates that bearer token authentication may be used to provide an OpenID Connect ID token. The ID token will be validated and mapped to a local user with an ID token validator. |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | The access token validators that may be used to verify the authenticity of an OAuth 2.0 bearer token. If this property is used to specify one or more access token validators, then only those validators will be used to verify access tokens. If no values are provided, then any access token validator configured in the server may be used. |
| Default Value | Any access token validator configured in the server may be used to validate access tokens. |
| Allowed Values | The DN of any Access Token Validator. |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | The ID token validators that may be used to verify the authenticity of an of an OpenID Connect ID token. If this property is used to specify one or more ID token validators, then only those validators will be used to verify ID tokens. If no values are provided, then any ID token validator configured in the server may be used. |
| Default Value | Any ID token validator configured in the server may be used to validate ID tokens. |
| Allowed Values | The DN of any ID Token Validator. |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
require-file-servlet-access-privilege
| Description | Indicates whether the servlet extension should only accept requests from authenticated clients that have the file-servlet-access privilege. This property only applies if the require-authentication property is set to true. If this property is set to true, then only requesters who have this privilege will be permitted to access content provided by this File Server HTTP Servlet Extension. If any require-group values are also specified, then only users who have the necessary privilege and are a member of at least one of the listed groups will be granted access. |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | The DN of a group whose members will be permitted to access to the associated files. If multiple group DNs are configured, then anyone who is a member of at least one of those groups will be granted access. This property will only be considered if the require-authentication property has a value of true. If authentication is required and one or more group DNs are configured, then only users that are members of at least one of those groups will be granted access. If no group DNs are configured, then any authenticated user will be granted access. |
| Default Value | None |
| Allowed Values | A valid DN. |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | The identity mapper that will be used to identify the entry with which a username is associated. This property will only be used when validating the credentials provided for basic authentication, and when the user is identified with a username rather than a DN. When authenticating with an OAuth 2.0 access token or an OpenID Connect ID token, the token validator's identity mapper will be used to perform the mapping. If no identity mapper is configured, then basic authentication will only be permitted for requests that identify the user by DN rather than with a username. |
| Default Value | Users may only be identified with DNs. |
| Allowed Values | The DN of any Identity Mapper. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
To list the configured HTTP Servlet Extensions:
dsconfig list-http-servlet-extensions
[--property {propertyName}] ...
To view the configuration for an existing HTTP Servlet Extension:
dsconfig get-http-servlet-extension-prop
--extension-name {name}
[--tab-delimited]
[--script-friendly]
[--property {propertyName}] ...
To update the configuration for an existing HTTP Servlet Extension:
dsconfig set-http-servlet-extension-prop
--extension-name {name}
(--set|--add|--remove) {propertyName}:{propertyValue}
[(--set|--add|--remove) {propertyName}:{propertyValue}] ...
To create a new File Server HTTP Servlet Extension:
dsconfig create-http-servlet-extension
--extension-name {name}
--type file-server
--set base-context-path:{propertyValue}
--set document-root-directory:{propertyValue}
[--set {propertyName}:{propertyValue}] ...
To delete an existing HTTP Servlet Extension:
dsconfig delete-http-servlet-extension
--extension-name {name}