Media repository

media_repo: The configuration for the media repository.

Venator’s media repository is quite a complex component that is incredibly flexible, so there are a number of configuration options to play with. Fear not, only a couple are necessary.

Root path

root_path: The root path to where media should be stored.

This can either be a fully qualified absolute path, or a relative path, or even point at a symlink. As long as the subdirectories local, remote, and external can be created at that location.

If the root_path does not exist, it will be created with 750 file permissions (rwxr-x---). The root path must not end in a trailing slash.

If the root path is not provided, the media repository will be disabled (but existing data will remain, if it exists).

Example:

media_repo:
  root_path: /mnt/media/venator

Temporary path

temp_path: The path to where temporary media files should be stored.

This can either be a fully qualified absolute path, or a relative path, or even point at a symlink. Temporary directories starting with the prefix venator_media_ must be creatable by the server.

If the temp_path does not exist, it will be created with 750 file permissions (rwxr-x---).

“temporary media files” are typically files that are being actively uploaded (i.e. before they’re properly saved), and thumbnails that are being worked on. It is unlikely that files will remain in this directory for more than a few seconds at a time.

It is safe to put the temporary directory on an ephemeral file system.

If the path is omitted, the system temporary directory (typically /tmp on Linux) will be used.

Example:

media_repo:
  temp_path: /mnt/media/venator

Max size

max_size_bytes: The maximum size (in bytes) of a single media item. Defaults to 100MiB (104857600).

Controls the maximum size of file uploads. Attempts to upload media files that are larger than this value will be rejected, even if the uploader is an administrator. The server will attempt to reject large uploads if their advertised Content-Length exceeds this value, but in cases where the Content-Length header is unavailable, the server will read up to max_size_bytes+1 bytes to determine whether the file is too large.

Important

The value of max_size_bytes MUST be less than or equal to max_request_bytes. Setting a value higher than max_request_bytes would cause the router component to reject the request for being too large before it could be passed to the media repository component for validation.

The server will refuse to start if this condition is not met.

Examples:

media_repo:
  max_size_bytes: 8388608  # 8MiB

media_repo:
  max_size_bytes: 26214400  # 25MiB

media_repo:
  max_size_bytes: 52428800  # 50MiB

media_repo:
  max_size_bytes: 104857600  # 100MiB

media_repo:
  max_size_bytes: 536870912  # 512MiB

media_repo:
  max_size_bytes: 1073741824  # 1GiB

Security

security: Configures the security-related settings for the media repository.

Because the media repository is a complex component that exclusively handles potentially untrusted user input, there are several security configurations available. The configuration for this is structured in such a way that the default values are typically sufficient for most people.

Disable remote media

disable_remote_media: If enabled, disables external/remote media functionality. Defaults to false.

When remote media is disabled, federated media will not be fetched, federated requests for media will be rejected, and server-side URL previews will be disabled.

Example:

media_repo:
  security:
    disable_remote_media: true

Disallow mime types

disallow_mime_types: Prevents files matching any of the given glob patterns from being uploaded to the media repository.

When a user attempts to upload a file, if the claimed Content-Type matches any of the given glob patterns, it will be rejected, even if they are an administrator.

Warning

The content type of encrypted files is application/octet-stream. Using a glob pattern that blocks this will effectively prevent users from uploading encrypted files.

Furthermore, Venator does not currently support MIME sniffing, so malicious users can work around this restriction by lying about or omitting the relevant header.

Example:

media_repo:
  security:
    disallow_mime_types:
      - image/*  # ban all images
      - application/vnd.microsoft.portable-executable  # ban EXE files
      - application/zip
      - application/x-zip-compressed
      - application/gzip
      - application/zstd  # ban compressed types

Only admins

only_admins: If true, only server administrators can upload media.

When enabled, regular users are unable to upload media. This can be used to restrict media uploads to only trusted users.

Example:

media_repo:
  security:
    only_admins: true

Disable checksums

disable_checksums: If true, disable checksum generation and comparison.

Venator makes use of SHA256 checksums to verify the integrity of media when utilising it. Typically, this means a SHA256 checksum is generated when the file has finished uploaded, and is then verified before it is transmitted to requesting clients. This prevents the file being tampered with on disk (although this is easily circumvented by just modifying the hash in the database). Over federation, Venator will include this SHA256 hash in the metadata part of the download, before sending the media content itself. This means other Venator servers that download media from this server will be able to verify the integrity of the downloaded file before processing it. This is not a Matrix behaviour and is currently exclusive to Venator.

Turning off checksums may improve performance as it avoids an extra disk round-trip, however this opens up the potential for corrupted or tampered files to be served.

Files that fail checksum validation are not immediately deleted, however will cause an error.

Example:

media_repo:
  security:
    disable_checksums: true  # not recommended

Minimum account age

minimum_account_age: The minimum age an account must be before it can upload files.

Restricts uploading media to accounts that have existed for longer than the given duration, excluding administrators.

Example:

media_repo:
  security:
    minimum_account_age: 5m  # 5 minutes

Disable server side thumbnails

disable_server_side_thumbnails: Disables server-side thumbnail generation.

Disabling server-side thumbnails may be desirable to reduce the amount of processing done on user-generated content, which is a large attack surface. The downside of this is thumbnails will generally be unavailable for uploaded media, such as user avatars, resulting in increased bandwidth and unhappy impatient users.

Example:

media_repo:
  security:
    disallow_server_side_thumbnails: true

ACL

acl (mapping, optional): An ACL event body that defines which servers are and aren’t allowed to communicate media. Applied after federation ACL.

Sets an access-control-list in the same way as room ACLs - servers in the allow are always allowed, unless they are denied in the deny list. You cannot create an ACL that bans the local server.

The ACL is bidirectional - forbidden servers won’t be able to download media from you, but you also won’t be able to download media from them.

Examples:

# Explicit denylist
media_repo:
  security:
    acl:
      allow: ["*"]  # Allow all servers
      deny:
        - evil.matrix.example  # Don't allow media communication with evil.matrix.example specifically.
        - "*.bad.matrix.example"  # Don't allow media communication with any server name under "bad.matrix.example".

# Explicit denylist
media_repo:
  security:
    acl:
      allow:
        - "SERVER_NAME_HERE"  # Your server name has to be explicitly listed
        - "good.matrix.example"  # Allow media communication with good.matrix.example
      # No need for an explicit `deny` here.

Enable streaming

enable_streaming: Allow streaming media over federation.

When enabled, media can be streamed directly to the requesting client before the server has finished downloading it over federation. This is incompatible with checksum verification, which will instead be ignored in this case. The benefit of this feature is that users can start streaming files from remote servers almost immediately, rather than having to wait for the homeserver to finish downloading it before uploading it again, which is particularly useful for videos. However, the lack of checksum verification, or preprocessing as a whole, means that other security protections may not be effective, and potentially invalid or illegal data may be sent to the client unknowingly.

You should evaluate how this fits into your threat model before changing this value.

Example:

media_repo:
  security:
    enable_streaming: true

Disallowed IP ranges

disallowed_ip_ranges: A list of IP ranges (CIDR notation) to refuse to connect to for remote/external media.

When this list is populated, Venator will refuse to connect to any address within these ranges, returning 403 / M_FORBIDDEN to the requesting user.

Supplying this option DISABLES the default filter. You MUST make sure you list EVERY network you want to disallow here.

Tip

By default, only global IP networks are permitted for remote media connections. If this configuration is not provided (see below warning), only external connections are permitted. This is the recommended configuration.

Caution

Never rely on the server to filter connections with 100% accuracy. There are no guarantees that the server will correctly determine which destination it is connecting to before dialling. If you need to make sure Venator never makes any unauthorised connections under any circumstances, it is imperative that you also enforce this with a firewall!

Example:

media_repo:
  security:
    disallowed_ip_ranges:
      - 127.0.0.0/8
      - 10.0.0.0/8
      - 172.16.0.0/12
      - 192.168.0.0/16
      - 100.64.0.0/10
      - 192.0.0.0/24
      - 169.254.0.0/16
      - 192.88.99.0/24
      - 198.18.0.0/15
      - 192.0.2.0/24
      - 198.51.100.0/24
      - 203.0.113.0/24
      - 224.0.0.0/4
      - ::1/128
      - fe80::/10
      - fc00::/7
      - 2001:db8::/32
      - ff00::/8
      - fec0::/10