Config Reference

Configure Imagizer using a JSON object. Retrieve and modify settings via the Admin API or User Data.

Imagizer Cloud supports most configurations through the Expert Configuration panel.

accessControl

Access to the Admin API can be restricted using the accessControl configuration. Access may either be limited using Basic Auth or completely disabled.

Enable Basic Authorization

{
   "accessControl":{
      "adminApi":{
         "basicAuth":{
            "username":"admin",
            "password":"mypassword"
         }
      }
   }
}

Completely Disable

DANGER

Access can be reactivated only through User Data.

{
   "accessControl":{
      "adminApi":{
         "enable":false
      }
   }
}

addResponseHeaders

Add custom response headers.

Alias: customHeaders

{
  "addResponseHeaders":[
     "X-Example-Header1: example1",
     "X-Example-Header2: example2"
  ]
}

allowAnimatedGifs

Allow Imagizer to convert animated GIFs. By default, only the first frame is rendered.

WARNING

Animated GIF support is resource intensive and may produce slow response times.

{
   "allowAnimatedGifs": true
}

allowDataUrls

Allow Imagizer to process data URLs. (default: false)

Example data URL

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==

Enable data URL support.

{  
   "allowDataUrls": true
}

allowDynamicOrigin

Allow Imagizer to dynamically set the backend using the origin, source_url or bucket parameters. (default: true)

Disable the origin, source_url, and bucket parameters.

{  
   "allowDynamicOrigin": false
}

allowOriginalImageRequest

Allow Imagizer to pass through the original image when no parameters are present. (default: true)

{  
   "allowOriginalImageRequest": true
}

applicationWorkers Not supported on Imagizer Cloud

Configure the process and fetch worker pools. By default, Imagizer auto-configures pool sizes based on available RAM.

• process pool: Should match or exceed maximum concurrent connections
• fetch pool: Should match or exceed maximum concurrent origin connections

Property	Description
autoConfig	When true Imagizer will auto configure the size of the application pools. (default: true)
process	The number of workers in the process pool.
fetch	The number of workers in the fetch pool.

TIP

Requires a reboot.

autoQuality New!

Automatic Image Quality Adjustment: Settings and Presets

Property	Description
method	The default value for the quality_method parameter. (ssim, mpe, smallfry)
preset	The default value for the quality_preset parameter.
presets	A list of preset targets for the comparison algorithms. Supports up to 25 presets.
qualityMin	The default value for the quality_min parameter.
qualityMax	The default value for the quality_max parameter.

{
  "autoQuality": {
    "method": "ssim",
    "preset": "medium",
    "presets": {
      "ssim": {
        "low": 0.999,
        "medium": 0.9999,
        "high": 0.99995,
        "veryhigh": 0.99999
      },
      "mpe": {
        "low": 1.5,
        "medium": 1,
        "high": 0.8,
        "veryhigh": 0.6
      },
      "smallfry": {
        "low": 100.75,
        "medium": 102.25,
        "high": 103.8,
        "veryhigh": 105.5
      }
    },
    "qualityMin": 20,
    "qualityMax": 100
  }
}

awsAuthorization

The name and credentials for a private S3 Bucket where your images are stored. Use this property or the backend property, but not both.

TIP

You must first create an AWS IAM Role or IAM User with a policy containing the s3:getObject permission.

Property	Description
bucket	The S3 bucket name.
key	The S3 auth key which has access to the bucket. (optional)
prefix	A prefix to be prepended to each S3 object key.
secret	The S3 secret which matches the key. (optional)
region	The region of the S3 bucket. (optional)
endpoint	The custom endpoint of the S3 backend. Useful for non-AWS S3 gateways. (optional)

Using an IAM Role.
Omit the credentials.

{  
   "awsAuthorization":{  
      "bucket":"my.s3.bucket"
   }
}

Using an AWS User.

{  
   "awsAuthorization":{  
      "bucket":"my.s3.bucket",
      "key":"S3_ACCESS_KEY_ID",
      "secret":"S3_SECRET_KEY"
   }
}

Non-AWS S3 Backends

Imagizer supports non-AWS S3 implementations. Use the endpoint property to pass custom endpoints.

Google Cloud Storage

To use Google Cloud storage, generate an HMAC key here, then use the custom endpoint https://storage.googleapis.com.

Example

{  
   "awsAuthorization":{  
      "bucket":"GOOGLE_STORAGE_BUCKET_NAME",
      "key":"HMAC_KEY",
      "secret":"HMAC_SECRET",
      "endpoint": "https://storage.googleapis.com"
   }
}

awsSystemsManager Not supported on Imagizer Cloud

Enable and configure AWS Systems Manager Parameter Store for sensitive configuration data

TIP

We strongly advise using an IAM role for credential provision. However, if necessary, you can use the optional key and secret properties. By default, the region is set to the region of the instance.

WARNING

AWS has rate limits on the Parameter Store API. Excessive requests may lead to throttling.

Enable AWS Systems Manager Parameter Store integration and optionally set the region.

{
 "awsSystemsManager": {
   "enable": true,
   "region": "us-east-1",
   "key": "",
   "secret": ""
 }
}

Parameter values are cached for the instance's lifespan. Changes to SSM parameters require a reconfiguration or reboot.

Example usage

Create a parameter in the AWS Systems Manager Parameter Store.

aws ssm put-parameter --name "MySecretParam1" --value "mysecret" --type SecureString

Create an IAM policy for permission to read the SSM parameter.

{
    "Action": [
        "ssm:GetParameter"
    ],
    "Resource": "arn:aws:ssm:us-east-1:ACC_NUMBER:parameter/MySecretParam*",
    "Effect": "Allow"
}

Use the SSM: prefix in sensitive configuration properties to reference a parameter store value.

{
   "awsSystemsManager": {
     "enable": true
   },
   "awsAuthorization":{  
      "bucket":"mybucket",
      "key": "mykey",
      "secret": "SSM:MySecretParam1"
   }
}

Full list of supported properties

Property
accessControl.adminApi.basicAuth.username
accessControl.adminApi.basicAuth.password
awsAuthorization.key
awsAuthorization.secret
backBlazeB2.keyId
backBlazeB2.applicationKey
cloudWatch.key
cloudWatch.secret
dataDog.key
googleCloudStorage.keyFile
nessusAgent.key

backBlazeB2

The configuration for using Backblaze B2 Native as an image storage backend

Property	Description
bucket	The name of the bucket
keyId	The key ID
applicationKey	The application key

{  
   "backBlazeB2":{  
      "bucket":"myb2bucket",
      "keyId": "XXXXXXXXXXXXXXXXXXXXXX",
      "applicationKey": "XXXXXXXXXXXXXXXXXXXXXX"
   }
}

backend

The base URL where your images are stored. Works with any publicly accessible URL, including S3 buckets. (default: http://s3.amazonaws.com)

For private S3 buckets, use awsAuthorization instead.

Set the backend to http://images.example.com.

{
   "backend": "http://images.example.com"
}

Set the backend to https://images.example.com.

{
   "backend": "https://images.example.com"
}

backendTimeout

The number of seconds to wait for a backend request to finish. (default: 15)

Set the backend timeout to 30 seconds.

{
   "backendTimeout": 30
}

backendConnectTimeout

The number of seconds to wait while trying to connect to the backend. (default: 5)

Set the backend connect timeout to 5 seconds.

{
   "backendConnectTimeout": 5
}

backendSync Not supported on Imagizer Cloud

Enable asynchronous uploads to a remote S3 backend using Amazon SQS queue and a local S3 backend for temporary storage of image files. Backend Sync allows for quick regional uploads with a central remote S3 backend.

Images are accessible for use immediately after uploading. Images will be asynchronously copied to the central S3 backend.

TIP

Requires the uploads configuration to be enabled.

TIP

You must first create an AWS IAM Role or IAM User with a policy containing the s3:getObject, s3:putObject, sqs:SendMessage, sqs:ReceiveMessage, sqs:GetQueueAttributes, sqs:ChangeMessageVisibility, and sqs:SendMessage, permissions.

Property	Description
awsAuthorization	The regional S3 backend to temporarily store images.
consumer	When true Imagizer will consume and process the backend sync jobs.
queue.sqs.endpoint	The AWS SQS endpoint.
queue.sqs.region	The AWS SQS region.
queue.sqs.key	The AWS SQS credential key. (optional)
queue.sqs.secret	The AWS SQS credential secret. (optional)

Enable backend sync for asynchronous uploads.

{
   "uploads": {
      "uploads": true
   },
   "awsAuthorization":{  
      "bucket":"my.central.s3.bucket",
      "key":"S3_ACCESS_KEY_ID",
      "secret":"S3_SECRET_KEY",
      "endpoint": "http://s3-api.us-geo.objectstorage.softlayer.net"
   },
   "backendSync": {
      "awsAuthorization": {      
          "bucket": "my.regional.s3.backend"
      },
      "consumer": true,
      "queue": {
          "sqs": {
            "endpoint": "https://sqs.us-east-1.amazonaws.com/aws-acount-number/sqs-queue-name",
            "region": "us-east-1"
          }
      }
   }
}

bucketsAllowed

Restrict the bucket parameter to a preset list of approved buckets.

TIP

Leaving bucketsAllowed empty will allow any bucket to be used.

Limit the use of the bucket parameter to three different buckets.

{  
   "bucketsAllowed": [
        "my.s3.bucket",
        "my.s3.bucket2",
        "my.s3.bucket3"
    ]
}

cache

Enable or disable image caching

Property	Description
memory	Cache all images in memory. (default)
none	Disable all caching.
originOnly	Cache only the original images in memory.

Enable disk cache.

{  
   "cache":"disk"
}

Disable caching completely.

{  
   "cache":"none"
}

cacheControl

Imagizer respects Cache-Control headers from origin images. TTL settings apply only when origins lack Cache-Control headers or when override is enabled.

Property	Description
override	When true override the origin Cache-Control header (default: false)
browserCacheTtl	Specifies the maximum time in seconds that the image is cached on the client side. This is the max-age directive. (Specified in seconds, default: 10 minutes)
serverCacheTtl	Specifies the maximum time in seconds that the image is cached on the server side in Imagizer. This is the s-maxage directive. (Specified in seconds, default: 30 days)

Override the cache control headers and set browser cache to 10 minutes and the Imagizer server cache to 30 days.

{  
   "cacheControl":{
      "override": true,
      "browserCacheTtl": 1800,
      "serverCacheTtl": 2678400
   }
}

consul Not supported on Imagizer Cloud

Register with a Consul agent on boot.
More Information

When configured, Imagizer will send a PUT request to the given endpoint with the given payload on boot. In case of failure, Imagizer will retry the request up to three times. The instance will continue to boot on failure with error log entries.

The properties of the payload can be auto-filled by Imagizer. Use one of the following variables.

Name	Description
$ip	The IP of the instance.
$host	The hostname of the instance.
$awsPublicIp	The AWS public IP address of the instance.
$awsPublicHost	The AWS public hostname of the instance.

{  
   "consul":{  
      "endpoint":"http://0.0.0.0:8500/v1/catalog/register",
      "payload":{  
         "Datacenter":"dc1",
         "Node":"$host",
         "Address":"$ip",
         "Service":{  
            "Service":"imagizer",
            "Port":80
         }
      }
   }
}

cluster Not supported on Imagizer Cloud

Distribute load across multiple Imagizer instances using Consistent Hashing with Bounded Loads.

TIP

The cluster configuration requires nodes to freely communicate with each other through ports 80, 17001, and optionally port 17006 for cache purging. Do not open port 17001 and 17006 to the public internet.

Property	Description
enable	When true, Imagizer will load balance requests across Imagizer instances specified in the nodes property.
hashBalanceFactor	Specify the balancing factor for bounded-load consistent hashing. (default: 125)
awsAutoScaleSync	When true, Imagizer will keep the nodes property synced with the current AWS auto-scaling group. (default: false)
includeQueryStringInHash	When true use the whole URL including parameters (not only the path part of the request) to build the load balancer hash. (default: false)
nodes	An array of Imagizer hosts (hostnames or IP addresses) of all the Imagizer nodes in the cluster.

Aws AutoScale Sync

When enabled, Imagizer will keep the nodes property synced with the current AWS auto-scaling group.

Enable cluster mode across an AWS AutoScaling group

{
  "cluster":{
    "enable": true,
    "awsAutoScaleSync": true
  }
}

To enable the functionality, specific IAM permissions are necessary.

It is advisable to employ an instance profile that has an associated IAM role.

Example IAM Policy Document

{
    "Action": [
        "ec2:DescribeInstances",
        "autoscaling:DescribeAutoScalingGroups",
        "elasticloadbalancing:DescribeTargetHealth"
    ],
    "Resource": "*",
    "Effect": "Allow"
}

Static Nodes

Alternatively, you can specify the nodes manually.

Enable cluster mode across a set list of Imagizer nodes.

{
  "cluster":{
    "enable": true,
    "nodes": [
      "10.0.0.1",
      "10.0.0.2",
      "10.0.0.3",
      "10.0.0.4"
    ]
  }
}

customHealthCheckEndpoint

Define a custom health check endpoint. The default endpoint /health will remain available even if a custom endpoint is set. The custom endpoint can also replace the default endpoint.

TIP

Useful for verifying that the configuration is correct and the system is running properly.

Property	Description
enable	Enable the custom health check endpoint. (default: false)
path	The custom health check endpoint path. (default: /healthcheck)
responseCode	The response code for the custom health check endpoint. (default: 200)
responseText	The response text for the custom health check endpoint. (default: healthy)

Set a custom health check endpoint to /healthcheck with a 200 response code and the text "healthy".

{
 "customHealthCheckEndpoint": {
  "path": "/healthcheck"
 }
}

Replace the default health check endpoint with a custom health check endpoint.

{
 "customHealthCheckEndpoint": {
  "path": "/health",
  "responseCode": 201,
  "responseText": "All good here!"
 }
}

defaultImages

Use default image in place of missing images and/or errors.

Property	Description
missing	Image to be used instead of 404 error code.
error	Image to be used instead of all other errors.
shouldProcess	If true process the default image using the given image parameters. (default: false)
return200Response	If true return a 200 response code with the default images. If false return the error code with the default image. (default: true)

Setup default error images.

{
   "defaultImages": {
      "missing": "http://example.com/404image.jpg",
      "error": "http://example.com/errorimage.jpg",
      "shouldProcess": false,
      "return200Response": true
   }
}

defaultImageParameters

Set global parameters applied to every request. Useful for adding compression and formatting without modifying image URLs.

TIP

Client-supplied URL parameters override these values.

Globally set quality to 75, format to auto, and limit the max image width to 1000px.

{  
   "defaultImageParams":{  
      "quality":75,
      "format":"auto",
      "width":1000
   }
}

defaultMobileImageParameters

Similar to the Default Image Parameters, Default Mobile Image Parameters are globally set for all image requests coming from a mobile device. These parameters will override any of the Default Image Parameters.

TIP

Client-supplied URL parameters override these values.

WARNING

Separate cache for mobile devices must be enabled from these parameters to work correctly.

Globally for mobile devices set quality to 65 and limit the max image width to 800px.

{  
   "defaultMobileImageParams":{  
      "quality":75,
      "width":800
   }
}

displayWelcomePage

When true display the Imagizer welcome page on the root path /. (default: true)

{  
   "displayWelcomePage": true
}

enablePostToProcess

Enable POST requests port 80. See the POST Requests guide for more information.

{  
   "enablePostToProcess": true
}

fallbackBackend

The fallback backend is used when the primary backend returns an error. The use of the fallback backend is optional. By default, the fallback backend is used when a 403 or 404 is received from the primary backend. See fallbackErrorCodes below to customize the error codes.

Property	Description
backend	The backend upstream server url.
backendTimeout	The backend fetch timeout. (default: 30 sec)
backendConnectTimeout	The backend fetch connect timeout. (default: 3 sec)
awsAuthorization	An AWS Authorization object. (optional)
fallbackErrorCodes	An array of http error codes to trigger the use of the fallback backend. (default: [404, 403])

Use a public fallback backend.

{
    "fallbackBackend": {
        "backend": "http://my.backup.s3.amazomaws.com"
    }
}

Use a private S3 fallback bucket.

{
    "fallbackBackend": {
        "awsAuthorization":{  
              "bucket":"my.backup",
              "key":"AWS_ACCESS_KEY_ID",
              "secret":"AWS_SECRET_KEY"
        }
    }
}

faceDetectionWidth

Determines the image width for the preprocessing of an image before applying facial detection. (default: 600)

{
   "faceDetectionWidth": 600
}

googleCloudStorage

The configuration for using Google Cloud Storage as an image storage backend.

TIP

You must first create a Service Account with the Storage Object Viewer role and generate a key file in JSON format.

Pass the full contents of the key file in the keyFile property or store the key file contents in AWS Systems Manager Parameter Store and reference it using the SSM: prefix.

Property	Description
bucket	The name of the bucket
projectId	The Google Cloud project ID
prefix	A prefix to be prepended to each object key.
keyFile	The key file contents in JSON form or SSM key.

Example

{  
   "googleCloudStorage":{  
      "bucket":"my-gcs-bucket",
      "projectId": "my-project-id",
      "prefix": "images/",
      "keyFile": {
        "type": "service_account",
        "project_id": "my-project-id",
        "private_key_id": "XXXXXXXXXXXXXXXXX",
        "private_key": "XXXXXXXXXXXXXXXXX",
        "client_email": "XXXXXXXXXXXXXXXXX@my-project-id.iam.gserviceaccount.com",
        "client_id": "XXXXXXXXXXXXXXXXX",
        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
        "token_uri": "https://oauth2.googleapis.com/token",
        "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
        "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/XXXXXXXXXXXXXXXXX@my-project-id.iam.gserviceaccount.com",
        "universe_domain": "googleapis.com"
      }
   }
}

healthCheck

The health check agent monitors various metrics, such as memory, CPU, and disk usage. Once specific thresholds are met, the agent will mark the instance's /health endpoint as unhealthy. Additionally, the health check agent will log the health and stats in the imagizer_health log service.

TIP

Setting any of the thresholds to 0 will disable the check.

Property	Description
enable	Enable the health check agent. (default: true)
memoryThreshold	The memory threshold in percent. (default: 95)
cpuThreshold	The cpu threshold in percent. (default: 0)
rootDiskThreshold	The root disk threshold in percent. (default: 90)
tmpDiskThreshold	The tmp disk threshold in percent. (default: 90)
http5XXThreshold	The http 5XX threshold in the number of 5XX errors per minute. Note: This metric includes origin errors, which may be undesirable. (default: 0)
checkInterval	The health check interval in seconds. (default: 15)
fallTrigger	The number of consecutive failed checks to trigger an unhealthy state. (default: 4)
riseTrigger	The number of consecutive successful checks to trigger a healthy state. (default: 1)
logInterval	The log interval in seconds to log the health status and stats. (default: 60)
logStats	When true log the instance's stats. (default: true)

Configure the health check agent.

{
  "healthCheck": {
     "enable": true,
     "memoryThreshold": 95,
     "cpuThreshold": 0,
     "rootDiskThreshold": 90,
     "tmpDiskThreshold": 90,
     "http5XXThreshold": 0,
     "checkInterval": 15,
     "fallTrigger": 4,
     "riseTrigger": 1,
     "logInterval": 60,
     "logStats": true
  }
}

hostsAllowed

Restrict the origin and source_url parameters to approved backends.

TIP

An empty list allows any origin.

Limit the use of the origin parameter to three different backends.

{  
   "hostsAllowed": [
        "bucket.s3.amazonaws.com",
        "bucket2.s3.amazonaws.com",
        "bucket3.s3.amazonaws.com"
    ]
}

hostsAllowedRegex

Similar to hostsAllowed, but allows for the use of regex matching.

Limit the use of the origin parameter to match one of two regex patterns. Will allow any subdomain of amazonaws.com and any subdomain of example.com or example.org.

{  
   "hostsAllowedRegex": [
        "amazonaws\\.com$",
        "example\\.(com|org)$"
    ]
}

hostConfigs Not supported on Imagizer Cloud

Enable separate configurations based on the request's host header.

The hostConfigs property takes an array of hostConfig objects. The hostConfig object is as follows:

Name	Description
extends	When true, extend the parent configuration. (default: false)
hostname	The hostname to which the config is mapped.
config	Imagizer config that will be applied to all requests with the given hostname.

WARNING

Some system configurations, such as stats and logging, are not available inside hostConfigs.

Examples

Multiple Origins

Configure two image origins mapped to imagizer1.example.com and imagizer2.example.com.

{
   "hostConfigs":[
      {
         "hostname":"imagizer1.example.com",
         "config":{
            "backend":"http://mybucket1-example.s3.amazonaws.com"
         }
      },
      {
         "hostname":"imagizer2.example.com",
         "config":{
            "backend":"http://mybucket2-example.s3.amazonaws.com"
         }
      }
   ]
}

In the above example, we mapped two separate configurations to different hostnames

Using the hostname imagizer1.example.com will fetch the image from the mybucket1-example.s3.amazonaws.com origin.

curl -H "Host: imagizer1.example.com" http://$IMAGIZER_HOST/myimage.jpg

Using the hostname imagizer2.example.com will fetch the image from the mybucket2-example.s3.amazonaws.com origin

curl -H "Host: imagizer2.example.com" http://$IMAGIZER_HOST/myimage.jpg

Multiple Sets of Default Parameters

Configure different default image parameters per hostname and extend the parent config.

{
   "backend": "http://mybucket1-example.s3.amazonaws.com",
   "hostConfigs":[
      {
         "extends": true,
         "hostname":"thumbnails.example.com",
         "config":{
            "defaultImageParams": {
              "width": 150,
              "height": 150,
              "quality": 60
            }
         }
      },
      {
         "extends": true,
         "hostname":"banners.example.com",
         "config":{
            "defaultImageParams": {
              "width": 1000,
              "height": 300,
              "quality": 80
            }
         }
      }
   ]
}

In the above example, all requests will use the origin http://mybucket1-example.s3.amazonaws.com. However, depending on the hostname used, the image will be scaled differently.

Requests using the thumbnails.example.com hostname will be resized to 150px by 150x

curl -H "Host: thumbnails.example.com" http://$IMAGIZER_HOST/myimage.jpg

Requests using the banners.example.com will be scaled to 1000px by 300px.

curl -H "Host: banners.example.com" http://$IMAGIZER_HOST/myimage.jpg

hostname Not supported on Imagizer Cloud

Set the hostname of the Imagizer instance on boot

set a static hostname

{
  "staticHostname": "my-imagizer-host1"
}

set a static hostname including domain

{
  "staticHostname": "my-imagizer-host1.example.com"
}

Perform a reverse DNS lookup to determine the hostname

{
  "reverseDnsLookup": true
}

ignoreCertWarnings

When true, ignore SSL errors from the backend.

{  
   "ignoreCertWarnings": true
}

ignoreFormats

Image formats to skip processing. These images pass through untouched.

{  
   "ignoreFormats": [
      "gif",
      "svg"
   ]
}

imageParamsAllowed

Restrict allowed parameter combinations to a preset list.

TIP

An empty list allows any parameter combination.

Limit the use of the image API to thumbnails of 120px wide and large images of 1000px wide with a watermarked logo image

{  
   "imageParamsAllowed": [
        {
            "width": 120
        },
        {
            "width": 500,
            "height": 500,
            "mark": "http://example.com/watermark.png",
            "mark_pos": "bottom,right",
            "mark_offset": 2
        }   
    ]
}

imageParamValidations

An array of validations to be applied to the request parameters on the Image API. An error will be returned to the user if any of the validations fail.

Property	Description
name	The name of the parameter. Any image parameters may be used.
required	Requires the parameter on all requests to the image API (default: false)
forbidden	Forbids the parameter on all requests to the image API (default: false, Takes precedence over required)
regex	An regex pattern for the parameter value to be matched against

Requires a watermark to be set by requiring the mark parameter to be present and match the given regex.

{
   "imageParamValidations":[
      {
         "name":"mark",
         "required":true,
         "forbidden":false,
         "regex":"#^/watermarks#"
      }
   ]
}

layers

Render text layers using the legacy render engine

Property	Description
legacyTextRender	Legacy text rendering (default: false)

Enable legacy text layer rendering

{
  "layers": {
    "legacyTextRender": true
  }
}

logging Not supported on Imagizer Cloud

Send logs to Syslog, AWS CloudWatch, or Datadog. Supports web access and application logs.

The application log has four levels: debug, info, warn, error. Default: info and above.

Property	Description
enable	Logging is enabled when true. (default: false)
appLogLevel	Defines the application level logging. (debug, info, warn, error) (default: info)
cloudWatch	Defines the AWS CloudWatch configuration.
dataDog	Defines the Datadog configuration.
legacy	When enabled legacy logging formats will be used. (default: false)
local	When true log to local disk. Local logs may be viewed at http://IMAGIZER_HOST:17006/logs. (default: false)
services	A list of logging services to be enabled. (default: imagizer_access, imagizer_access_err, imagizer_app, imagizer_system, imagizer_health)
syslog	Defines Syslog configuration.
trustedProxies	A list of IPs or CIDRs of trusted proxies to allow real IP address from using the X-Forwarded-For header. We recommend using 0.0.0.0/0 for AWS Load balancers.

Access Log Format

The access logs are an extended combined format.

Nginx Log Format

log_format  main  '$remote_addr - $remote_user [$time_local] '
                  '"$request" $status $body_bytes_sent "$http_referer" '
                  '"$http_user_agent" "$http_x_forwarded_for" '
                  '$host $request_time '
                  '$upstream_http_x_original_filesize $upstream_http_x_original_resolution '
                  '$upstream_http_x_origin_fetch_time $upstream_http_x_original_response_code';```

Example Log Entry

127.0.0.1 user-identifier user [05/Aug/2021:17:44:17 +0000] "GET /image.jpg?width=200 HTTP/1.1" 200 24000 "https://example.com" "Mozilla/5.0..." "127.0.0.1, 127.0.0.2, 127.0.0.3" xxxxx.imagizer.com 0.320 988376 2000x2000 292 200

A "-" in a field indicates missing data.

• 127.0.0.1 is the IP address of the client (remote host) which made the request to the server.
• user-identifier is the RFC 1413 identity of the client. Usually "-".
• user is the userid of the person requesting the document. Usually "-" unless .htaccess has requested authentication.
• [05/Aug/2021:17:44:17 +0000] is the date, time, and time zone that the request was received, by default in strftime format %d/%b/%Y:%H:%M:%S %z.
• "GET /image.jpg?width=200 HTTP/1.1" is the request line from the client. The method GET, /image.jpg?width=200 the resource requested, and HTTP/1.1 the HTTP protocol.
• 200 is the HTTP status code returned to the client. 2xx is a successful response, 3xx a redirection, 4xx a client error, and 5xx a server error.
• 24000 is the size of the object returned to the client, measured in bytes.
• https://example.com is the HTTP Referrer URL.
• "Mozilla/5.0..." is the user agent from the client.
• "127.0.0.1, 127.0.0.2, 127.0.0.3" is the X-Forwarded-For header chain of IP addresses.
• xxxxx.imagizer.com is the hostname of the request.
• 0.320 is the total time spent processing the request.
• 988376 is the file size of the origin image before processing.
• 2000x2000 is the resolution of the origin image before processing.
• 292 is the fetch time in milliseconds from the origin image storage.
• 200 is the http status code from the image origin fetch.

Services

• imagizer_access The access logs in the combined format.
• imagizer_access_err The access error log. Formatted as a standard Nginx error log.
• imagizer_app The Imagizer application log.
• imagizer_system The Imagizer system log.
• imagizer_stats_collector The Imagizer stats collection log.
• nginx_varn An internal access log. Used for debugging purposes. (default: disabled)
• nginx_varn_err An internal access error log. Used for debugging purposes. (default: disabled)
• imagizer_admin_access The admin access logs (from port 17006) in the combined format.
• imagizer_admin_access_err The admin access error log. Formatted as a standard Nginx error log.
• imagizer_health The health check agent logs.
• imagizer_health_acess The access logs for /health checks. (default: disabled)

syslog

Property	Description
facility	Sets facility of syslog messages, as defined in RFC 3164. (Default: local7)
server	Defines the address of a syslog server. The address can be specified as an IP address or hostname.
port	Defines the port of a syslog server. (default: 514)
protocol	Specifies the protocol for syslog. Valid options include udp and tcp. (default: udp)

Enable Syslog Logging

{  
   "logging":{  
      "enable": true,
      "appLogLevel": "info",
      "syslog": {
         "server": "syslog-server.example.com",
         "facility": "local7",
         "port": 514,
         "protocol": "tcp"
      }
   }
}

cloudWatch

CloudWatch Logging may be enable and authorized using either an IAM role attached to your Imagizer instance or AWS user credentials.

Property	Description
enable	Enables web server and application logging to Cloud Watch. (default: false)
region	The AWS Cloud Watch region to send logs to.
key	The AWS auth key which has access to the Cloud Watch. (optional)
secret	The AWS secret which matches the key. (optional)

TIP

You must first create an AWS IAM Role or IAM User with a policy containing the logs:CreateLogGroup, logs:CreateLogStream, logs:PutLogEvents, and logs:DescribeLogStreams permissions.

Enable CloudWatch Logging using IAM Role

{  
   "logging":{  
      "enable": true,
      "appLogLevel": "info",
      "cloudWatch": {
         "enable":true
      }
   }
}

Enable CloudWatch Logging using AWS credentials

{  
   "logging":{  
      "enable": true,
      "appLogLevel": "info",
      "cloudWatch": {
         "enable":true,
         "key": "XXXXXXXXXXXXXXXXX",
         "secret": "XXXXXXXXXXXXXXXXX"
      }
   }
}

datadog

Property	Description
enable	When true Imagizer will send logs to Datadog. (default: false)
key	Your Datadog API key.

Enable DataDog Logging

{  
   "logging":{  
      "enable": true,
      "appLogLevel": "warn",
      "dataDog": {
         "enable":true,
         "key": "XXXXXXXXXXXXXXXXX"
      }
   }
}

maxImageDimensions

Limit the maximum dimensions allowed for images. This limits the original image as well as any processed images. By default, Imagizer will limit the dimensions of images to 5000px by 5000px.

Parameter	Description
enable	When true enable the Max Image Dimensions limit.
width	The max allowed width of an image.
height	The max allowed height of an image.

Limit the max dimensions of images to 3500px by 3500px

{
   "maxImageDimensions":{  
      "enable":true,
      "width":3500,
      "height":3500
   }
}

nessusAgent

Set up the Nessus Agent configuration

The Nessus Agent will be linked when configured and on boot.

Parameter	Description
key	The Nessus key. (Required)
flags	A list of flags to pass to the agent link command.

Enable the Nessus Agent using Tenable Cloud

{
  "nessusAgent": {
    "key": "XXXXXXXXXXXXXXXXXXXXXXXXX",
    "flags": [
      "--cloud"
    ]
  }
}

Enable the Nessus Agent using Nessus Manager with groups

{
  "nessusAgent": {
    "key": "XXXXXXXXXXXXXXXXXXXXXXXXX",
    "flags": [
      "--host=nessus-manager.example.com",
      "--port=8834",
      "--groups=group1,group2"
    ]
  }
}

Disable and unlink the Nessus Agent

{
  "nessusAgent": {
    "enable": false
  }
}

TIP

See awsSystemsManager for more information on how to use the Nessus Agent with AWS Systems Manager.

network

Set up a static IP network configuration.

WARNING

Network configuration is supported only on Imagizer Enterprise.

TIP

Network configuration is supported only through a config loader on bootup.

TIP

Imagizer will try and determine the correct network interface if one is not supplied.

Set static IP address.

{
    "static": true,
    "interface": "ens3",
    "ip": "192.168.2.86",
    "netmask": "255.255.255.0",
    "gateway": "192.168.2.1",
    "dnsServers": [
        "75.75.75.75",
        "75.75.76.76"
    ]
}

passThroughRequestHeaders

Imagizer will pass through request headers to the origin image only when specified in the config. Use the passThroughHeaders parameter to specify an array of headers to be use on each origin image request. Wildcards (*) are supported to match multiple headers.

Pass the Host, Origin, and X-My-Custom-Header headers through to the origin.

{  
   "passThroughRequestHeaders":[  
      "Host",
      "Origin",
      "X-My-Custom-Header"
   ]
}

Pass all request headers

{
   "passThroughRequestHeaders":[  
      "*"
   ]
}

passNonImagizerParamsToOrigin

When true, allow passing non-Imagizer HTTP parameters to the image origin. (default: true)

Disable sending any HTTP parameters to the image origin

{
  "passNonImagizerParamsToOrigin": false
}

presetColors

Defines a list of custom colors that may be used by the colorize API.

{
   "presetColors":[
      {
         "name":"sepia",
         "value":"235,95,25"
      },
      {
         "name":"lush",
         "value":"0,128,0"
      },
      {
         "name":"citron",
         "value":"128,128,0"
      },
      {
         "name":"wave",
         "value":"0,128,128"
      },
      {
         "name":"berg",
         "value":"100,128,180"
      }
   ]
}

sentinelOne

Sentinel One Agent configuration

Imagizer will register the agent when configured and on boot.

{
  "sentinelOne": {
    "token": "this.should be.your.token.string"
  }
}

stats Not supported on Imagizer Cloud

Imagizer collects system and application stats, available via the Admin API. Optional integrations: Ganglia, Datadog, CloudWatch, and Prometheus.

ganglia

Send all stats to Ganglia. Stats are sent once a minute.

WARNING

AWS EC2 does not support multicast. Use the default udp protocol.

Property	Description
enable	If true send all stats to ganglia.
host	The ganglia host.
port	The ganglia port (default: 8649).
protocol	The protocol to use when sending stats to ganglia. (udp or multicast) (default: udp)

Enable Ganglia Stats

{  
   "stats":{
      "ganglia":{  
         "host":"ganglia.example.com",
         "port":8649,
         "protocol":"udp"
      }
   }
}

cloudWatch

Send all stats to AWS CloudWatch. Stats are sent once a minute.

CloudWatch stats may be authorized using either an IAM role attached to your Imagizer instance or AWS user credentials.

Property	Description
enable	Enables Cloud Watch stats. (default: false)
region	The AWS Cloud Watch region to send stats to.
key	The AWS auth key which has access to the Cloud Watch. (optional)
secret	The AWS secret which matches the key. (optional)

TIP

You must first create an AWS IAM Role or IAM User with a policy containing the cloudwatch:PutMetricData permission.

Enable CloudWatch using IAM Role.

{  
   "stats":{  
      "cloudWatch":{  
         "enable":"true",
         "region":"us-east-1"
      }
   }
}

Enable CloudWatch Metrics using AWS credentials.

{  
   "stats":{  
      "enable": true,
      "cloudWatch": {
         "enable":true,
         "key": "XXXXXXXXXXXXXXXXX",
         "secret": "XXXXXXXXXXXXXXXXX"
      }
   }
}

datadog

Send system stats (CPU, memory, disk, processes) and Imagizer application stats to Datadog.

Property	Description
enable	When true Imagizer will send stats to Datadog (default: false).
key	Your Datadog API key.
namespace	Prepend all stats with this namespace string.
tags	An array of tags which will be applied to all Datadog metrics and logs. Data Dog Tagging

Enable DataDog Stats

{  
   "stats":{  
      "enable": true,
      "appLogLevel": "warn",
      "dataDog": {
         "enable":true,
         "key": "XXXXXXXXXXXXXXXXX",
         "namespace": "imagizer",
         "tags": [
            "region:us-east1",
            "env:production"
         ]
      }
   }
}

prometheus

Export system stats (CPU, memory, disk, processes) and application stats via Node Exporter.

Metrics available at http://$IMAGIZER_HOST:9100/metrics when enabled.

TIP

Starting with Imagizer v14.3-89.16, Prometheus metrics are also available through the Admin API at http://$IMAGIZER_HOST:17006/metrics.

Property	Description
enable	When true Node Exporter will collect stats.
namespace	Prepend all stats with this namespace string.

{  
   "stats":{  
      "enable": true,
      "prometheus": {
         "enable":true
      }
   }
}

secureWebProxy

Using a secure web proxy will send all secure (https) origin image requests to a specified proxy.

TIP

For non-https traffic, see webProxy.

All https traffic will pass through my-proxy-example.com on port 8282.

{  
   "secureWebProxy":{  
      "host":"my-proxy-example.com",
      "port":"8282"
   }
}

separateMobileCache

Cache separate versions for mobile and desktop devices. Required for Default Mobile Image Parameters.

Enable Separate Mobile Cache

{  
    "separateMobileCache": true
}

WARNING

Always enabled on Imagizer Cloud.

separateWebpCache

Cache separate versions for WebP-capable and non-WebP clients based on the Accept header. Required for format=auto.

Enable Webp Cache

{  
    "separateWebpCache": true
}

WARNING

Always enabled on Imagizer Cloud.

separateHostCache

Enable Host Cache

Use separate cache zones for each hostname used. (default: false)

{  
    "separateHostCache": true
}

svgSanitize

Configure Imagizer to sanitize SVG images to prevent XSS attacks. (default: strip)

Value	Description
strip	Strip dangerous tags, such as <script>. (default)
error	Return a 400 error when dangerous tags detected.
none	Do not sanitize SVG images.

Example JSON configuration to return a 400 error when dangerous tags are detected:

{  
    "svgSanitize": "error"
}

uploads

Allow image uploads with an S3 backend using POST Requests.

TIP

Requires a S3 Backend to be configured.

TIP

You must first create an AWS IAM Role or IAM User with a policy containing the s3:putObject permission.

Property	Description
enable	Enables unloads on port 17005.
enablePort80	Enables unloads on port 80. (default: false)

{  
   "uploads":{  
      "enable":true
   },
   "awsAuthorization":{  
      "bucket":"my.s3.bucket"
   }
}

upscaleAllowed

Allow Imagizer to upscale images beyond their original dimensions. (default: false)

Allow upscaling of images.

{
  "upscaleAllowed": true
}

urlRewrites

Perform search-and-replace on request URLs before processing. Modify paths or query parameters. Supports both string and regex (PCRE) patterns. Multiple rewrites allowed.

Property	Description
search	The value being searched for, otherwise known as the needle.
replace	The replacement value that replaces found search values.
includeQueryString	If true include the query string in the search and replace. (default: false)
isRegex	If true treat the search string as a regex. (default: false)

Modify the image path of all requests. Replace "is/image" with "product/published".

/is/image/myimage1.jpg?width=400 => /product/published/myimage1.jpg?width=400

{
   "urlRewrites":[  
      {  
         "search":"is/image",
         "replace":"product/published"
      }
   ]
}

Migrate previously used image optimizer URLs to Imagizer formatted API

/images/myimage1.jpg?resize=300x400 => /images/myimage1.jpg?width=300&height=400

{  
   "urlRewrites":[  
      {  
         "search":"/resize=([0-9]+)x([0-9]+)/",
         "replace":"width=$1&height=$2",
         "includeQueryString":true,
         "isRegex":true
      }
   ]
}

webProxy

Using a web proxy will send all origin image requests to a specified proxy.

TIP

For https traffic, see secureWebProxy.

All http traffic will pass through my-proxy-example.com on port 8281.

{  
   "webProxy":{  
      "host":"my-proxy-example.com",
      "port":"8181"
   }
}