いまさら聞けない
NGINX コンフィグ
F5ネットワークスジャパン合同会社
NGINX テクニカルソリューションズアーキテクト
鈴木 孝彰

本日の目的
• NGINXを触る機会が増えてきた方
• 公式ドキュメントや書籍もあるけどNGINXコンフィグから
挙動を想像するのは慣れてない方
• 今さらNGINXコンフィグを聞けない！と思っている方
そんな方達のちょっとしたお助けになれればと思います.

今日紹介するもの
• if
• map, geo
• location
• rewrite
• add_header
• proxy_add_header
• sub_filter
• js_import
• health_check
• match
• api

このスライドでは
• NGINX version 1.19.1
• NGINX Plus R22
を利用しています.

本日利用するNGINXコンフィグ
https://github.com/takaakisuzuki/f5-nginx-community

NGINX Configコンテキスト
• Main Config ファイル
/etc/nginx/nginx.conf
• Default Configファイル
/etc/nginx/conf.d/default.conf

if
if ( $http_user_agent ~ ’curl’) {
set $flag = 0;
}
if ( $http_user_agent ~ ’Android’) {
set $flag = 1;
}
if ( $http_user_agent ~ ’Windows’) {
set $flag = 2;
}
if ( $http_user_agent ~ ’Macintosh’) {
set $flag = 2;
}

if
演算子 意味
なし
変数名, 変数の値が空の文字列また
は 0 の場合は false
=, != 変数と文字列の比較
~, !~ 大文字と小文字を区別する比較
~*, !~* 大文字と小文字を区別しない比較
-f, !-f ファイルの存在をチェック
-e, !-e
ファイル、ディレクトリ、シンボリ
ックリンクの存在を確認
-x, !-x 実行可能ファイルのチェック
if ( $http_user_agent ~ ’curl’) {
set $flag = 0;
}
if ( $http_user_agent ~ ’Android’) {
set $flag = 1;
}
if ( $http_user_agent ~ ’Windows’) {
set $flag = 2;
}
if ( $http_user_agent ~ ’Macintosh’) {
set $flag = 2;
}

if
簡単に書けるのでコンフィグが長くなる原因の一つ
演算子 意味
なし
変数名, 変数の値が空の文字列また
は 0 の場合は false
=, != 変数と文字列の比較
~, !~ 大文字と小文字を区別する比較
~*, !~* 大文字と小文字を区別しない比較
-f, !-f ファイルの存在をチェック
-e, !-e
ファイル、ディレクトリ、シンボリ
ックリンクの存在を確認
-x, !-x 実行可能ファイルのチェック
if ( $http_user_agent ~ ’curl’) {
set $flag = 0;
}
if ( $http_user_agent ~ ’Android’) {
set $flag = 1;
}
if ( $http_user_agent ~ ’Windows’) {
set $flag = 2;
}
if ( $http_user_agent ~ ’Macintosh’) {
set $flag = 2;
}

map
map $http_user_agent $flag {
default unknown;
“~ELB-Health-Checker” aws;
“~Android” mobile;
”~iPhone” mobile;
“~Macintosh” pc;
“~Windows” pc;
}
location /pc/ {
if( $flag != ‘mobile’ ){
return 403;
}
…
}
location /mobile/ {
if( $flag != ‘pc’ ){
return 403;
}
…
}

map
map $http_user_agent $flag {
default unknown;
“~ELB-Health-Checker” aws;
“~Android” mobile;
”~iPhone” mobile;
“~Macintosh” pc;
“~Windows” pc;
}
location /pc/ {
if( $flag != ‘mobile’ ){
return 403;
}
…
}
location /mobile/ {
if( $flag != ‘pc’ ){
return 403;
}
…
}
Win/Macで動作しているブラウザ
からのリクエストは許可
Android/iPhoneで動作している
ブラウザからのリクエストは許可
複数条件の場合にはmapの利用を
NGINXチームでは推奨

geo
geo $country {
default JP;
127.0.0.0/24 US;
127.0.0.1/32 US;
10.1.0.0/16 SG;
192.168.1.0/24 JP;
2001:0db8::/32 JP;
}
location /pc/ {
if( $country != ‘JP’ ){
return 403;
}
…
}
http://nginx.org/en/docs/http/ngx_http_geo_module.html

geo
geo $country {
default JP;
127.0.0.0/24 US;
127.0.0.1/32 US;
10.1.0.0/16 SG;
192.168.1.0/24 JP;
2001:0db8::/32 JP;
}
location /pc/ {
if( $country != ‘JP’ ){
return 403;
}
…
}
デフォルトは $remote_addr を利用して
クライアント送信元IPを複数条件判断
カントリーコードによってコンテンツを変更
v
http://nginx.org/en/docs/http/ngx_http_geo_module.html

location
location /application/ {
…
}
location = /application/0/ {
…
}
location ~ /APPLICATION/[0-9]/ {
…
}
location ~* /application/[0-9][0-9]/ {
…
}

location
location /application/ {
…
}
location = /application/0/ {
…
}
location ~ /APPLICATION/[0-9]/ {
…
}
location ~* /application/[0-9][0-9]/ {
…
}
プレフィックス 意味
なし 前方一致
= 完全一致
~ 大文字小文字を区別する正規表現
~* 大文字小文字を区別しない正規表現

location
location /application/ {
…
}
location = /application/0/ {
…
}
location ^~ /application/01/ {
…
}
location ~ /APPLICATION/[0-9]/ {
…
}
location ~* /application/[0-9][0-9]/ {
…
}

location
プレフィックス 意味
なし 前方一致
= 完全一致
^~ 優先一致
~ 大文字小文字を区別する正規表現
~* 大文字小文字を区別しない正規表現
優先一致の場合は正規表現プレフィックスは処理しない.
location /application/ {
…
}
location = /application/0/ {
…
}
location ^~ /application/01/ {
…
}
location ~ /APPLICATION/[0-9]/ {
…
}
location ~* /application/[0-9][0-9]/ {
…
}
v

location, 実際の使われ方:例
恒久的なファイルを指定
location /application/ {
…
}
location = /robots.txt {
…
}
location ^~ /images/ {
…
}
location ~* ^(/.+)¥.(jpg|jpeg|jpe|png|gif)$ {
…
}
何らかの理由でリクエストに’/images/’が含まれてない場合の対策
リクエストに’/images/’が含まれていれば
正規表現処理は通さない
v
v
v

rewrite
rewrite ^/([a-z]+)/(.+)/([0-9])$ /application/ last;
location /application/ {
…
}
location = /application/0/ {
…
}

rewrite
rewrite ^/([a-z]+)/(.+)/([0-9])/$ /application/ last;
location /application/ {
…
}
location = /application/0/ {
…
}
http://192.168.1.236/test/aaa/0/
オプション 意味
last リライト先も処理
break リライト処理を終わる
正規表現 意味
[a-z]+ 英子文字を1回以上繰り返し
.+ 改行を除く全ての文字を1回以上繰り返し
[0-9] 数字1文字
メタ文字 意味
^ 先頭
$ 末尾

rewrite
rewrite ^/([a-z]+)/(.+)/([0-9])$ /application/ last;
rewrite ^/エンジンエックス.* /application/ last;
location /application/ {
…
}
location = /application/0/ {
…
}
http://192.168.1.23/エンジンエックス
日本語も設定可能ですが個人的に推奨はしません
正規表現 意味
.* 改行を除く全ての文字を0回以上繰り返し

rewrite, 利用例
rewrite ^/([a-z]+)/(.+)/([0-9])$ /application/ last;
rewrite ^/エンジンエックス.* /application/ last;
# 現状 http://localhost/city/11aa/2222/
# 新サービス http://localhost/demo/demo.php?pre_id=11aa&city_id=2222
rewrite ^/city/(.*)/(.*)/$ /demo/demo.php?pre_id=$1&city_id=$2 last;
location /demo/ {
…
}
location = /application/0/ {
…
}

rewrite, 利用例
rewrite ^/([a-z]+)/(.+)/([0-9])$ /application/ last;
rewrite ^/エンジンエックス.* /application/ last;
# 現状 http://localhost/city/11aa/2222/
# 新サービス http://localhost/demo/demo.php?pre_id=11aa&city_id=2222
rewrite ^/city/(.*)/(.*)/$ /demo/demo.php?pre_id=$1&city_id=$2 last;
location /demo/ {
…
}
location = /application/0/ {
…
}
キャプチャグループ 意味
(…) $1, $2の変数が利用可能
メタ文字 意味
^ 先頭
$ 末尾

rewrite, 利用例
location ~* ^(/.+)¥.(jpg|jpeg|jpe|png|gif)$ {
root /usr/share/nginx/html;
rewrite ^(.+) /images/nginx.png break;
}
正規表現 意味
(jpg|jpeg|jpe|png|gif) サブパターン開始終了
オプション 意味
last リライト先も処理
break リライト処理を終わる
プレフィックス 意味
なし 前方一致
= 完全一致
^~ 優先一致
~ 大文字小文字を区別する正規表現
~* 大文字小文字を区別しない正規表現

add_header
upstream backend {
server 127.0.0.1:80;
}
…
location /demo/ {
add_header 'X-Proxy-Header' "F5 NGINX Community add_header" always;
add_header Strict-Transport-Security "max-age=63072000" always;
proxy_pass http://backend/;
} オプション 意味
always 応答コードに関係なく追加
NGINXからクライアントに
ヘッダーを付与

proxy_set_header
upstream backend {
server 127.0.0.1:80;
}
…
location /set-header/ {
proxy_set_header X-Forwarded-for $remote_addr;
proxy_set_header X-Community-name 'F5 NGINX Community’;
proxy_pass http://backend/response/;
}
location /response/ {
default_type text/plain;
return 200 "arded-for: $http_x_forwarded_for ¥n X-Community-name: $http_x_community_name";
}
NGINXからバックエンドに
ヘッダーを付与
変数 意味
$http_xxx_xxx 任意ヘッダーの取得可能

sub_filter
location /demo/ {
sub_filter 'client_browser' '$http_user_agent’;
sub_filter 'request_id' '$request_id’;
sub_filter 'nginx_version' '$nginx_version’;
sub_filter 'document_root' '$document_root';
sub_filter 'proxied_for_ip' '$http_X_Forwarded_for';
sub_filter 'request_uri_path' '$request_uri';
sub_filter 'rewrite_uri_path' '$uri?$args’;
proxy_pass http://backend/
}
コンテンツの内容を
NGINXで変更
コンテンツ文字列 置換したい文字列
大文字小文字を区別しない 変数を含めることができる
http://nginx.org/en/docs/http/ngx_http_sub_module.html

js_import
js_import js/http.js;
js_import js/f5nginx.js;
…
location /hello/ {
js_content http.hello;
}
location /f5nginx/ {
js_content f5nginx.hello;
}
root@6903ed032f67:/# dpkg -l | grep nginx-module-njs
ii nginx-module-njs 1.19.1.0.4.2-1~buster arm64 nginx njs dynamic modules
http.js
function hello(r) {
r.return(200, ”Hello World!¥n");
}
export default {hello}
F5nginx.js
function hello(r) {
var dt = new Date().getTime();
var uuid = 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
var rand = (dt + Math.random()*16)%16 | 0;
dt = Math.floor(dt/16);
return (c=='x' ? rand :(r&0x3|0x8)).toString(16);
});
r.return(200, "F5-NGINX Community!¥n" + uuid);
}
http://nginx.org/en/docs/http/ngx_http_js_module.html#js_import
NGINXチームで開発が
進んでいるプロジェクト

match welcome {
status 200;
header Content-Type = text/html;
body ~ " F5 NGINX Community";
}
location / {
health_check interval=3 match=welcome;
proxy_pass http://backend/;
}
health_check, match
NGINX Plus 機能

Parameter Use
Interval [5] ヘルスチェックの間隔
Fails [1] 最大失敗回数
Passes [1] 最小成功回数
Uri [/] へルスチェックURIパス
http://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html#health_check
health_check

• status - 応答コードをチェックする
• status 200;
• status ! 400 402;
• status 200-399;
• header – ヘッダーをチェックする
• header Content-Type = text/html;
• header Cache-Control;
• header Connection ~ close;
• body – コンテンツをチェックする
• body ~ “Hello World”
• body !~ “Hello World”
http://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html#match
match

ヘルスチェック状態の確認
NGINX Plus ダッシュボード

api, NGINX Plus ダッシュボード
location /api {
api write=on;
allow 192.168.1.0/24;
}
location = /dashboard.html {
root /usr/share/nginx/html;
}
NGINX Plus
REST API有効
NGINX Plus
パッケージに含まれています
http://demo.nginx.com/
http://demo.nginx.com/swagger-ui/
NGINX Plus ダッシュボード:
NGINX Plus REST リファレンス:

gRPC
Server
gRPC
Server
Active
Health Check
Active
Health Check
5G/LTE
 NGINX Plusアクティブヘルチェックにより適切なgRPCサーバへロードバランシング
 NGINX PlusをDockerで利用するのでAWS ECSの親和性が高く、シンプル構成
 AWS ECSを利用し大量アクセス時にも対応
NGINX Plus 導入後
gRPC Client
gRPC Client
gRPC Client
大手企業様
gRPC
Proxy
gRPC GET
ヘスルチェック

まとめ
NGINXコンフィグについて解説しました.
多くの環境で使われているNGINX挙動が少しでも伝わると嬉しいです.
様々なサービスでNGINXを活用していただければと思います.

https://www.nginx.co.jp/free-trial-request/

ありがとうございました.
Thank you