nginxでエラー文言を制御する

はじめに

WEBサーバを開発する際に有名なnginxのエラー設定方法を調べたため、まとめました。
nginxはエラーが発生したときに静的なエラーをユーザに返却することができます。そのエラーをオリジナルのものにする方法をまとめました。

環境

• Ubuntu:18.04.2
• nginx:18.04.2

インストール

apt install nginxでインストールするだけです。

エラーの制御

普通エラーはpython側で制御しますが、タイムアウトなどでnginxがエラーを返却する場合があります。その際にデフォルトではnginxの文字がエラー文言に含まれセキュリティ的に問題があったり、システム全体の統一性を崩すため、オリジナルのエラーを返却したいことがあります。/etc/nginx/nginx.confまたは/etc/nginx/conf.d/xxx.confのserverコンテキストを修正することで可能になります。

エラーのファイル

オリジナルのhtmlファイルやjsonファイルをユーザに返却する場合はserverコンテキスト内にオリジナルのファイルの設定とhttpステータスとオリジナルのファイルの紐づけを設定します。

オリジナルのファイルの設定の形式はこのようになります。

    location = /設定名(ファイル名) {
        root オリジナルのhtmlが格納されたパス
    }

httpステータスとオリジナルのhtmlの紐づけの形式はこのようになります。

    error_page httpステータス /設定名(ファイル名);

confファイルの全体はこのようになります。
これでnginxが500、502、503、504を返却するときに/flask/nginx/50x.htmlがユーザに返却されます。
※下の例で50x.htmlを50x.jsonにするとjsonを返却します。

sample.conf

server {
    listen       8010;
    server_name  original;

    limit_conn servers 2;
    
    location / {
        include uwsgi_params;
        uwsgi_pass unix:///tmp/uwsgi.sock;
    }

    # httpステータスと50x.html設定を紐づけ
    error_page 500 502 503 504 /50x.html;

    # 50x.htmlの設定
    location = /50x.html {
        # htmlが格納されたパス
        root /flask/nginx;
    }
}

エラーのファイルとhttpステータスの変更

上の場合では、httpステータスは発生したステータスがユーザに返却されますが、場合によってはステータスも指定したい場合があります。紐づけの設定を変更することで実現できます。
この場合、=とhttpステータスの間にスペースを入れないように注意してください。

httpステータスとオリジナルのファイルの紐づけの形式はこのようになります。

    error_page httpステータス =返却したいhttpステータス /設定名(ファイル名);

confファイルの全体はこのようになります。
これでnginxが500、502、503、504を返却するときにhttpステータス500、/flask/nginx/50x.htmlがユーザに返却されます。

sample.conf

server {
    listen       8010;
    server_name  original;

    limit_conn servers 2;
    
    location / {
        include uwsgi_params;
        uwsgi_pass unix:///tmp/uwsgi.sock;
    }

    # httpステータスと返却用ステータス、50x.html設定を紐づけ
    error_page 500 502 503 504 =500 /50x.html;

    # 50x.htmlの設定
    location = /50x.html {
        # htmlが格納されたパス
        root /flask/nginx;
    }
}

エラーの文言

ファイルではなく、単純なテキストやconfファイルに返却値を記載することもできます。その場合はserverコンテキスト内にオリジナルの設定とhttpステータスと設定の紐づけを行います。

エラーの設定の形式はこのようになります。

    location = /設定名 {
        return 返却するメッセージ;
    }

httpステータスと設定の紐づけの形式はこのようになります。

    error_page httpステータス /設定名;

confファイルの全体はこのようになります。
これでnginxが500、502、503、504を返却するときに"オリジナルエラー"がユーザに返却されます。

sample.conf

server {
    listen       8010;
    server_name  original;

    limit_conn servers 2;
    
    location / {
        include uwsgi_params;
        uwsgi_pass unix:///tmp/uwsgi.sock;
    }

    # httpステータスと50x設定を紐づけ
    error_page 500 502 503 504 /50x;

    # 50xの設定
    location = /50x {
        # 返却するメッセージ
        return "オリジナルエラー";
    }
}

エラーの文言とhttpステータスの変更

上の場合では、httpステータスは発生したステータスがユーザに返却されますが、場合によってはステータスも指定したい場合があります。エラーの設定を変更することで実現できます。

エラーの設定の形式はこのようになります。

    location = /設定名 {
        return 返却するhttpステータス 返却するメッセージ;
    }

confファイルの全体はこのようになります。
これでnginxが500、502、503、504を返却するときにhttpステータス500、"オリジナルエラー"がユーザに返却されます。

sample.conf

server {
    listen       8010;
    server_name  original;

    limit_conn servers 2;
    
    location / {
        include uwsgi_params;
        uwsgi_pass unix:///tmp/uwsgi.sock;
    }

    # httpステータスと50x設定を紐づけ
    error_page 500 502 503 504 /50x;

    # 50xの設定
    location = /50x {
        # 返却するメッセージ
        return 500 "オリジナルエラー";
    }
}

おわりに

nginxでエラーを制御する方法をまとめました。nginxは色々な機能があるためエラーを返却する機会も多いかと思います。その場合にエラー形式を統一すると見やすくかっこよいものになるため、こだわれるならこだわったほうが良いと思いました。