P4 Software
/
BarcoderX English
Applies to: BarcoderX Basic and Ultimate
Status: Built, not yet released. This page is for the person who puts the label service where other people can reach it. The service is a small program, described in The label service. It speaks plain http and it is meant to sit behind a web server that you run. The two configurations below are references, written from the documentation of nginx and Caddy, except the two lines that set
X-Forwarded-Proto, which are written from general knowledge of those programs and were not checked in their documentation. They have not been run against a live service yet, so test them before you rely on them.
The service has limits of its own: the size of a template, the time of a request, the number of requests and connections of a caller, and the time it gives a caller to take an answer. They keep one caller from using the whole service. They are the last line, not the first. Put a web server in front of it, and let that server do four things:
Required before a public launch. These four are required before you let anyone you do not know reach the service. Two more points do not depend on the web server: the pictures and the commands carry the evaluation mark until a license is registered, and the service is not for production use. Keep the .NET runtime that runs the service up to date.
Edit settings.json next to the program:
{
// Listen on this computer only. Only the proxy reaches the service.
"listenAddress": "http://127.0.0.1:5187",
// Believe the address that the proxy reports, from this proxy only.
"network": {
"trustForwardedHeaders": true,
"trustedProxies": ["127.0.0.1"]
}
}
With these settings:
127.0.0.1 is believed when it carries X-Forwarded-For, and the service takes the last address in that header, the one the proxy added itself (network.trustedProxyHops is 1 by default). The addresses to its left were sent by the caller and are ignored. A connection from any other address keeps its own address.limits.maxConnectionsPerClient, because all callers come through it. Limit them at the proxy, as below.X-Forwarded-Proto itself. The service sends Strict-Transport-Security only when the listed proxy says https (the entry at the right end of the header), so a proxy that passes the header of the caller on unchanged lets a caller on plain http make the service send it. The configurations below overwrite it. If your proxy serves plain http too, it must write http there. To send no such header at all, set network.sendStrictTransportSecurity to false.If the proxy runs on another computer, list its address in network.trustedProxies and set listenAddress to an address of this computer that only the proxy can reach. An entry is a single address (10.0.0.5, 2001:db8::5) or a range (10.0.0.0/8), at most 32 entries. A range must be written exactly (10.0.0.1/8 is refused: its start is 10.0.0.0). "Any address" (0.0.0.0 or ::) and a range that covers every address or almost every address (0.0.0.0/0, ::/0, any range wider than /8 for IPv4 or /7 for IPv6, since two halves would cover everything too) are refused; such a range is allowed only if you also set network.acceptAnyProxyAddress to true, which you should not do, because then every caller is a trusted proxy and can choose its own address.
This is a complete server block with the settings that matter. The comments say what each part is for. The numbers are a first choice: the template limit of the service is 262,144 bytes by default, and the largest answers are 2,000,000 bytes (a picture) and 16,777,216 bytes (printer commands), so the buffers below hold the answers of a picture and spill the larger ones to a temporary file.
# Reference configuration for nginx in front of the BarcoderX label service.
# Change the name, the certificate paths and the numbers to fit your site.
# Count the connections and the requests of each client address.
# 10 MB of shared memory holds the state of many thousands of addresses.
limit_conn_zone $binary_remote_addr zone=bx_conn:10m;
limit_req_zone $binary_remote_addr zone=bx_req:10m rate=30r/m;
upstream barcoderx_label_service {
server 127.0.0.1:5187;
keepalive 8;
}
server {
listen 443 ssl;
server_name labels.example.com;
ssl_certificate /etc/ssl/labels.example.com/fullchain.pem;
ssl_certificate_key /etc/ssl/labels.example.com/privkey.pem;
# A caller that sends its headers or its template slowly is dropped here,
# and so is a caller that is slow to take the answer.
client_header_timeout 10s;
client_body_timeout 10s;
send_timeout 15s;
# The service refuses a template over 262144 bytes (its default). Refuse it here first.
client_max_body_size 300k;
# At most 20 connections and a steady 30 requests a minute for each address,
# with a burst of 10. The service has its own, smaller limits behind this.
limit_conn bx_conn 20;
limit_req zone=bx_req burst=10 nodelay;
location / {
proxy_pass http://barcoderx_label_service;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_set_header Host $host;
# Add the address of the caller to the header. $proxy_add_x_forwarded_for is
# what the caller sent, with the address nginx saw appended at the end. The
# service believes only that last address.
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
# Say which scheme the visitor used, replacing whatever the caller sent. The
# service sends the Strict-Transport-Security header only when this says https.
proxy_set_header X-Forwarded-Proto $scheme;
# Read the whole request here before the service sees it, and read the
# whole answer from the service at once. A slow caller then spends nginx's
# time, not a place of the service.
proxy_request_buffering on;
proxy_buffering on;
proxy_buffers 16 64k;
proxy_busy_buffers_size 128k;
proxy_max_temp_file_size 32m;
proxy_connect_timeout 3s;
proxy_send_timeout 15s;
proxy_read_timeout 15s;
}
}
Caddy gets a certificate by itself for a real host name. This is a Caddyfile with the same intent. The comments say what each part is for.
# Reference configuration for Caddy in front of the BarcoderX label service.
# Change the host name and the numbers to fit your site.
{
servers {
timeouts {
# A caller that sends its headers or its template slowly is dropped,
# and so is a caller that is slow to take the answer.
read_header 10s
read_body 10s
write 20s
idle 30s
}
max_header_size 16KB
}
}
labels.example.com {
# The service refuses a template over 262144 bytes (its default). Refuse it here first.
request_body {
max_size 300KB
}
reverse_proxy 127.0.0.1:5187 {
# Read the whole request here before the service sees it, and read the
# whole answer from the service at once. Make the second number at least
# as large as the largest answer you allow (limits.maxOutputBytes and
# limits.maxCommandsBytes), or the answer is streamed and a slow caller
# reaches the service.
request_buffers 300KB
response_buffers 20MB
# Caddy sets X-Forwarded-For to the address it saw and, by default, ignores
# the value that the caller sent. That is what the service needs.
# Do not add trusted_proxies here unless another proxy is in front of Caddy.
# Say which scheme the visitor used, replacing whatever the caller sent. The
# service sends the Strict-Transport-Security header only when this says https.
header_up X-Forwarded-Proto {http.request.scheme}
}
}
Caddy does not limit the connections or the requests of one address by itself. Do it where your system allows: a firewall rule that counts the connections of each address, or a module for Caddy that limits requests. The service's own limits stay in force, but they are the last line only.
App Service ends https at its network load balancers, and the app receives plain http. The load balancer is inside the private address ranges, and Microsoft's page for ASP.NET Core apps (configure-language-dotnetcore, the section "Detect HTTPS session") says to trust three private ranges and that they cannot be narrowed down further. List them in the settings:
"network": {
"trustForwardedHeaders": true,
"trustedProxies": ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]
}
The page writes the same ranges as ::ffff:10.0.0.0/104, ::ffff:172.16.0.0/108 and ::ffff:192.168.0.0/112; the service accepts that form too and treats it as the same. Without this, the service sees every visitor as the load balancer, so all visitors share one request at a time and one rate limit.
The same two settings make the service send the Strict-Transport-Security header: the load balancer tells the app that the visitor used https (X-Forwarded-Proto: https), and the service believes it only because the load balancer is listed. Nothing else is needed. To switch the header off, set network.sendStrictTransportSecurity to false (see Label service).
What to know about it:
X-Forwarded-For: with network.trustedProxyHops at its default of 1, the last entry. Addresses to its left are the caller's own claims and are ignored, so a visitor cannot choose its own address by sending the header, even a visitor whose own address is inside the listed private ranges. If you put another listed front end in front of App Service, set network.trustedProxyHops to 2, list the front end, and restrict the app so that only that front end can reach it. That has a price: with two hops, a visitor that connects from inside the listed ranges can choose the address it is counted as, once, and the limits per caller do not hold for it. More hops make it worse, so use no more than the chain has. An address that carries a port is read without the port.X-Forwarded-For: 203.0.113.9 and see that the forged address is not the one counted.Do not try to list the addresses of Front Door. There are hundreds of ranges (the service tag AzureFrontDoor.Backend), they change, the service accepts at most 32 entries, and other Azure customers use the same addresses (origin-security). The service recognizes your Front Door by proof instead:
AzureFrontDoor.Backend with the header filters x-azure-fdid (the Front Door ID of your profile) and x-forwarded-host (your host names), and deny everything else. Azure then answers 403 to every other request, before the service sees it. This includes the azurewebsites.net address of the app and the default azurefd.net name of the Front Door.Tell the service in settings.json (the ranges are the three private ranges of App Service from the section above, and the hops stay at 1):
"network": {
"trustForwardedHeaders": true,
"trustedProxies": ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"],
"trustedProxyHops": 1,
"edge": {
"mode": "azureFrontDoor",
"frontDoorId": "<the Front Door ID of your profile>",
"hosts": ["<the host name your visitors type>"]
}
}
The service does not start if the ID is not written as the portal shows it, if the host list is empty, or if network.trustedProxyHops is not 1. The message says what to change.
/health/live and /health/ready, which the platform's own health check needs): it checks again that the connection comes from your web server, that there is exactly one X-Azure-FDID and that it is your ID, and that there is exactly one X-Forwarded-Host and that it is one of your host names. A request that fails is refused with 403 and BX6024, before the body is read, and uses nobody's allowance. If all is right, it removes the last entry of X-Forwarded-For (the address of Front Door itself, written by App Service) and then reads one hop as before: the caller is the address that Front Door saw, and everything to its left is the visitor's own claim.What to know about it:
settings.json only when you deploy, and do not share that file.azurewebsites.net address of the app, and another to the default azurefd.net name of the Front Door, must both be answered 403 (by Azure, with no BarcoderX code in the answer). Do it after every deploy and once a day.X-Forwarded-For: Front Door writes it, and App Service then writes Front Door's own address. Send 30 requests through Front Door, each with a different forged X-Forwarded-For: 203.0.113.N: the later ones must be answered 429 (too many requests). If they are not, the layout is different from what the service expects, and the edge mode must not be used until that is understood.X-Azure-FDID: <your ID> header: it must also be answered 403. (Whether Front Door replaces or adds to a header that the visitor sent is not stated in the pages that were read; the service refuses a request that carries two ID values, so the second case is refused either way.) Delete the throwaway profile afterwards: a profile is billed until it is deleted.hosts in their xn-- form. A name with a port, a dot at the end or a list of names does not match.After you start the proxy and the service, check from another computer:
curl https://labels.example.com/health/live answers {"status":"ok"}.curl https://labels.example.com/api/v1/meta/limits lists the limits of the service.Retry-After header. If the answer is 429 for a caller on its own after a single request, the service sees every caller as the proxy: check network.trustForwardedHeaders and network.trustedProxies.Whatever the proxy does, the service keeps these limits, and you can read the numbers at /api/v1/meta/limits:
limits.bodyReadMilliseconds (5 seconds), so a slow sender holds no place for drawing (the server also stops a sender that sends fewer than 240 bytes a second on average once its first 5 seconds are over, whatever that setting says); and a place for drawing only while the label is laid out and drawn;Three budgets can be full at the same time, and the memory of the host has to hold all of them, on top of what the runtime itself uses:
limits.memoryBudgetMegabytes (1,024 MB by default);limits.outputBudgetMegabytes (128 MB by default);limits.memoryBudgetMegabytes (256 MB by default).At the defaults that is 1,024 + 128 + 256 = 1,408 MB, so give the service at least 2 GB, and more if you use the server garbage collector, which keeps memory the program has freed for longer. If you raise limits.maxBodyBytes for the web editor, raise limits.memoryBudgetMegabytes as well: it counts 60 times the body limit for each request, on top of its picture and its text.
One more amount is held outside these budgets for a moment: a caller that asks for printer commands as JSON (Accept: application/json) makes the JSON document in memory before it is counted in the pool of answers, which is about the size of the commands (at most about twice limits.maxCommandsBytes, which is 16 MB by default, in the worst case) for each request that asks for it at that moment. With the defaults, one caller makes one request at a time (limits.maxRequestsInFlightPerClient), so this is up to tens of megabytes per caller that asks, and it is given back as soon as the answer is counted or refused. A JSON answer larger than the whole pool is refused with BX6019 and no Retry-After; the plain text of the same commands always fits the pool.
A request for the pictures of single elements (POST /api/v1/render/elements) holds more memory than a picture. The worst request found, 64 filled and rounded elements of 40 millimeters at 300 dpi, allocated 299 to 319 MB over its life, and its memory peaked 136 MB above the start in a fresh process and up to 270 MB in one that had been running, because the collector lets garbage build up when it has been busy. The service assumes 350 MB for the engine, the encoder of the pictures and the answer, 16 MB more as room, and, as for every request, 60 times the body limit and 1.7 KB for each character of the label. At the defaults that is about 390 MB, which is more than one place holds (about 207 MB), so such a request takes two of the places. At the default budget (1,024 MB) there are four places, so while one request for elements runs, pictures are still drawn and a second request for elements can run; a third is refused at once with BX6006. A caller can also make only 6 requests for elements a minute by default (rateLimit.elementRequestsPerMinutePerClient), so one caller cannot keep the places for itself. With a smaller limits.memoryBudgetMegabytes a request for elements takes more of the places, or all of them; with a larger one there are more places and more of these requests run together. The figure is measured, not guessed: a test repeats the measure on every build and fails if the worst request allocates more than the figure.
The service limits what one address can do, and since the template is read before a place for drawing is taken, a slow sender no longer holds the few places for drawing. It still cannot tell real callers apart when many addresses together are the problem. The proxy of this page is therefore required for a public service, not an extra. These gaps remain, and each was measured:
limits.bodyReadMilliseconds (5 seconds), and is then stopped with BX6017. It holds no place for drawing, so ordinary callers are served meanwhile. A proxy that buffers the whole request body before it passes the request on takes even that cost away. The proxy_request_buffering on line of the nginx example and the request_buffers line of the Caddy example do that. Test it with a slow sender before you rely on it.Connection: close, the service waits one second for the rest of the body, and cuts the connection if it has not come. So a refusal no longer keeps its connection for several seconds, but enough addresses can still fill the total. Limit the connections of each address and the time of a request header at the proxy, as the examples do.rateLimit.requestsPerMinuteAllClients), and a new caller is then refused with BX6014 although it did nothing wrong. Only a rate limit at the proxy can tell real callers apart.limits.maxRequestsInFlightPerClient. A proxy does not help here, because it sees the same shared address; it only matters that the service reads the caller address from the proxy (network.trustForwardedHeaders) when the proxy sits in front of it.type member of a problem document is an address under docs.barcoderx.example. The real domain is not decided yet, and nothing follows the address.BarcoderX is a product of P4 Software.
Was this page helpful?