Skip to content

ngx_mruby v2.7.3

Choose a tag to compare

@matsumotory matsumotory released this 31 Oct 15:08
591147b

ngx_mruby 2.7.3 is a maintenance release of the 2.x line. It changes some
behavior that an existing configuration, Ruby script or build can observe;
read "Behavior changes: read before upgrading" in the notes before you
upgrade. No directive was added, renamed or removed: rebuild the module the
way you built 2.7.2 and replace the binary or the dynamic module.

Security

This release fixes two issues reachable by the clients whose requests or
datagrams reach an operator's configuration. Each has its own advisory:

  • High — A use-after-free in the stream Nginx::Stream::Async.sleep
    path, reachable by a client of a UDP stream server, is fixed (CWE-416).
    (GHSA-86wx-fcwx-m3vh)
  • Low — A string with a NUL byte passed to Nginx::Upstream#server= or
    the stream upstream_server= could put uninitialized worker memory into
    the upstream server's name; fixed (CWE-200, CWE-908).
    (GHSA-8r78-rxqq-5gp5)

Both are fixed in 2.7.3. See the "Fixes" section (the first, #645) and entry 9
of the notes (the second) for what each changes and what to do (nothing, for
a configuration that upgrades).

Behavior changes: read before upgrading

1. Nginx::SSL::ACME::Dehydrated#auto_cert_deploy reads the standard error of dehydrated, so that it accepts the terms of service of the CA, and accepts them at most once per call (#636)

  • Before: #auto_cert_deploy of the auto-ssl mrbgem read only the standard
    output of dehydrated. dehydrated 0.5.0 and later write the request to accept
    the terms of service of the CA to standard error, so the method did not see
    it and did not call #auto_accept_terms. With a dehydrated account that was
    not registered yet, dehydrated stopped, no certificate was stored, and the
    handshake failed: Nginx::SSL#certificate_data= raised TypeError for the
    missing certificate. What dehydrated wrote to standard error reached
    error.log as raw lines, without a time or a level. With dehydrated 0.4.0,
    which writes the request to standard output, the method called
    #auto_accept_terms and then itself again, with no limit: when the
    registration failed, the next run asked again, and the method ran dehydrated
    in the handshake until the mruby stack was exhausted.
  • Now: #auto_cert_deploy runs dehydrated with its standard error joined to
    its standard output (2>&1). It sees the request, #auto_accept_terms
    registers the account (dehydrated --register --accept-terms), and
    #auto_cert_deploy runs dehydrated once more, which gets the certificate.
    It accepts the terms at most once per call: when the second run asks again,
    because the registration failed, the method returns without a certificate
    after two runs of dehydrated. All that --cron writes, standard error
    included, is in the [info] lines that the method writes with
    Nginx::SSL.log. The method returns nil, as before.
  • Why it changed:
    • The defect: the tests of the auto-ssl mrbgem that this pull request adds
      (test/t/cases/auto_ssl.rb, with dehydrated 0.7.2 and the ACME test
      server Pebble) found that a new account never got a certificate. The
      method was written for dehydrated 0.4.0, the version in
      test/conf/auto-ssl/dehydrated, which wrote the request to standard
      output. The review of the pull request found that a failed registration
      then made the method run dehydrated without end: dehydrated 0.7.2 removes
      the account key that it made when the registration fails, so every run
      asks for the terms again. The tests reproduce it with a Pebble that
      requires external account binding.
    • Why the old behavior could not be kept: the method finds the request in
      what dehydrated printed. With standard error kept apart, it cannot find it
      with any dehydrated that speaks ACME v2 (0.6.0 and later), and ACME v2 is
      the only version that Let's Encrypt has served since it turned off ACME v1
      in 2021. Once the method finds the request, a CA that refuses the
      registration (one that requires external account binding, an outage, a
      rate limit on new accounts) would keep the worker in the handshake without
      the limit.
    • What the documentation promised:
      docs/class_and_method/README.md refers to
      the scripts in mrbgems/auto-ssl/mrblib for the API and says nothing
      about the output of dehydrated. #auto_accept_terms and the check in
      #auto_cert_deploy exist to accept the terms of service on the first run.
  • Affected: TLS handshake handlers that call
    Nginx::SSL::ACME::Dehydrated#auto_cert_deploy, as
    test/conf/auto-ssl/nginx.conf.dehydrated_example does. With an error_log
    level above info (the examples use notice), the messages that
    dehydrated --cron writes to standard error, its errors included, no longer
    appear in error.log.
  • What to do: nothing to get a certificate with a new account. To see the
    errors of dehydrated --cron in error.log, set the level of the
    error_log that the server uses to info. Code that relied on the method
    retrying the registration within one call calls it again in a later
    handshake, which runs dehydrated again.
  • Not changed by this release: #auto_accept_terms still reads only the
    standard output of dehydrated --register --accept-terms; what that command
    writes to standard error, such as "Error registering account key", still
    reaches error.log as raw lines.

2. A content handler that calls Nginx::Async.sleep answers after the sleep (#646)

  • Before: mruby_content_handler* code could call Nginx::Async.sleep
    without an exception, but nginx did not wait for it: the request ended at
    the sleep, the client got no response, and the code after the sleep did not
    run. The connection was closed, or kept open for the next request of the
    client without an answer to this one. A subrequest to a location whose
    content handler sleeps, for example one that Nginx::Async::HTTP.sub_request
    sends, got the output of that handler, but nginx then logged
    http request count is zero at level alert, and the connection did not
    answer the next request of the client.
  • Now: nginx waits for a content handler that sleeps. The code after the
    sleep runs, and the request gets what the handler writes with Nginx.rputs
    or Nginx.echo, or the status that it returns with Nginx.return, as when
    the handler does not sleep. A handler that sleeps more than once answers
    after its last sleep. When the handler raises after the sleep, the request
    gets 500, as in the other handlers. A subrequest to such a location gets
    its output, and the connection goes on. After the sleep,
    Nginx::Async::HTTP.sub_request raises a RuntimeError in a content
    handler, so the request gets 500: nginx would not finish the request after
    that subrequest. In 2.7.2 that code did not run.
  • Why it changed:
    • The defect: the content phase finalized the request with the NGX_DONE
      that the handler returned while its fiber waited, so nginx freed the
      request before the timer of the sleep fired, and the cleanup of the
      request deleted that timer. The 2.7.1 release notes list this under
      Known limitations and plan a release that
      lets a content handler wait; the owner decided on 2026-10-04 that the
      content handler supports Nginx::Async.sleep instead of raising.
    • Why the old behavior could not be kept: the code after the sleep can run
      only if the request stays until the sleep ends, and a request that stays
      is answered. The other way to remove the defect was to raise a
      RuntimeError in the content handler, as in a log handler, which would
      break code that calls the method there without an exception today.
    • What the documentation promised:
      docs/class_and_method/README.md
      said that the method does not raise in a content handler and that the
      request ends at the sleep without a response, and it listed the set,
      rewrite and access handlers as the places where the method works.
  • Affected: mruby_content_handler and mruby_content_handler_code code
    that calls Nginx::Async.sleep, and subrequests to a location with such
    code. Such a request now stays open for the time of the sleep and then gets
    a response.
  • What to do: nothing for code that expects its response after the sleep.
    Code that relied on the sleep to end the request without a response gets a
    response now: to close the connection without one, return
    Nginx::HTTP_CLOSE (444) with Nginx.return instead. Send a subrequest
    from a rewrite or access handler, not after a sleep in a content handler.
  • Not changed by this release: a content handler that runs in the location
    that Nginx.redirect runs from Ruby code still ends the request at the
    sleep, without its output. The handler that called Nginx.redirect goes on
    after the call and may answer the request itself, and the output of the
    sleeping handler would follow that response.

3. An exception in the location that Nginx.redirect runs ends the handler of that location, and nginx finishes the request (#646)

  • Before: Nginx.redirect "/path" runs the handlers of /path before it
    returns. When an mruby handler or filter of /path raised, for example its
    content handler, rewrite handler or header filter, the exception reached
    the code that called Nginx.redirect as if the call had raised it, and the
    code after the call did not run. When that code did not rescue the
    exception, the calling handler answered 500; when it rescued it, the client
    got no response. In both cases nginx did not finish the request: the
    connection stayed open after the response until the client closed it, the
    access log got no line for the request, and stub_status counted the
    connection as active until the worker exited.
  • Now: the exception ends the handler of /path as it does without the
    redirect, and the request gets 500 unless its response was already
    started. Nginx.redirect returns, and the code after it runs, as when
    /path does not raise. nginx finishes the request, writes its access log
    line and closes the connection. When the handler that called
    Nginx.redirect ends with the 500 that /path left in the status, nginx
    tries to send that status again and logs header already sent at level
    alert, as it already does when a handler returns a status after the
    response of the redirect target. The error.log lines of the exception
    stay the same, except that an exception in a header filter is logged once
    instead of twice.
  • Why it changed:
    • The defect: mruby passes the exception that ends a fiber resumed from C
      by longjmp to the innermost running mruby VM. The handler of /path runs
      in a fiber of its own inside the Ruby call of the handler that called
      Nginx.redirect, so the exception jumped over the nginx functions
      between the two (ngx_http_internal_redirect and the checkers of the
      phases), which finish the request. The tests of this pull request,
      test/t/cases/redirect_to_raising_handler.rb, show the connection that
      stays open.
    • Why the old behavior could not be kept: nginx finishes the request only
      in the functions that the exception jumped over, so the request could not
      end while the exception reached the calling code. Stopping the exception
      at the handler of /path lets the request end, and the calling code then
      goes on as it does after a redirect to a location that does not raise.
    • What the documentation promised:
      docs/class_and_method/README.md
      said that the other location returns the response to the client, and
      said nothing about an exception in it.
  • Affected: code that calls Nginx.redirect with an internal location whose
    mruby handlers or filters raise, and code that rescued such an exception
    around Nginx.redirect. Such code no longer sees the exception, and the
    code after the call runs.
  • What to do: nothing for code that did not rescue the exception. Code that
    rescued it around Nginx.redirect to react to a failure of the redirect
    target moves the rescue into the code of that location.
  • Not changed by this release: when the handler that called Nginx.redirect
    answers the request, with a status or an exception, while a rewrite handler
    of the redirect target still sleeps in Nginx::Async.sleep, the output of
    that rewrite handler follows the response on the connection when its timer
    fires.

4. A stream session goes on or ends after Nginx::Stream::Async.sleep by the result of its code, and an exception after the sleep no longer aborts the next session (#651)

  • Before: after Nginx::Stream::Async.sleep, only code that left
    Nginx::Stream::Connection.stream_status at Nginx::Stream::DECLINED, the
    default, let the session go on. When the code raised, or set the status to
    Nginx::Stream::ABORT, Nginx::Stream::OK or another value, nginx neither
    ended nor continued the session: the client got nothing until it closed the
    connection, and the session stayed until the worker exited. An exception
    after the sleep also stayed in the mruby state that the sessions of the
    stream {} block share, and the next session that the worker handled, in
    any server of the block, was aborted before its code ran; error.log
    logged the earlier exception again for that session.
  • Now: after the sleep, the session goes on or ends as it does when the code
    does not sleep: Nginx::Stream::DECLINED goes on with the next handler,
    Nginx::Stream::OK with the next phase, Nginx::Stream::DONE and
    Nginx::Stream::AGAIN leave the session waiting, and an exception,
    Nginx::Stream::ABORT or another status ends the session. An exception
    after the sleep is logged once, for its own session, and the next session
    runs its code.
  • Why it changed:
    • The defect: nginx's checker of the access phase handles the result of a
      handler that returns at once. A handler that sleeps returns NGX_DONE
      to it, and the timer that resumes the code dropped the result of the code
      after the sleep, except for NGX_DECLINED. After an exception it did not
      clear the exception from the shared mruby state either, as the code
      without the sleep does, and ngx_stream_mrb_start_fiber of the next
      session read it as its own. The HTTP handlers got the same clearing in
      2.7.1 (#550).
    • Why the old behavior could not be kept: a session whose result is
      dropped is never ended or continued, and an exception that stays in the
      shared state ends a session that did not raise it. Handling the result
      as nginx's checker does is what ends or continues the session.
    • What the documentation promised:
      docs/class_and_method/README.md
      documented Nginx::Stream::Async.sleep for the access phase and
      Nginx::Stream::Connection.stream_status= with Nginx::Stream::ABORT to
      deny a client, and said nothing about the result after the sleep.
  • Affected: mruby_stream and mruby_stream_code code that calls
    Nginx::Stream::Async.sleep and then raises, or sets
    Nginx::Stream::Connection.stream_status to a value other than
    Nginx::Stream::DECLINED; and the next stream session that the worker
    handled after such an exception.
  • What to do: nothing for code that sets Nginx::Stream::ABORT after the
    sleep to deny a client: the session now ends. Code that set
    Nginx::Stream::OK after the sleep now goes on with the next phase, for
    example proxy_pass; set Nginx::Stream::ABORT instead where the session
    must not go on.

5. Nginx::Upstream and Nginx::Stream::Connection raise TypeError for an argument that is not a String (#652)

  • Before: Nginx::Upstream.new, Nginx::Upstream#server=,
    Nginx::Stream::Connection.new and Nginx::Stream::Connection#upstream_server=
    read their argument as a String without checking its class. With nil,
    the two setters read through a null pointer, and the worker process
    stopped with a segmentation fault. With another object that is not a
    String, the result depended on how mruby stores that object: the worker
    could stop in the same way, or the method read the memory of the object as
    if it were the bytes of a string.
  • Now: the four methods raise TypeError ("... cannot be converted to
    String") for an argument that is not a String, before they look up the
    upstream or change its server. A String, also an instance of a subclass of
    String, works as before.
  • Why it changed:
    • The defect: the methods took the argument with mrb_get_args(mrb, "o", ...)
      and read it with RSTRING_LEN and RSTRING_PTR, which are valid only for
      a String (src/http/ngx_http_mruby_upstream.c,
      src/stream/ngx_stream_mruby_connection.c). The tests of this pull
      request, test/t/cases/upstream_server_checks.rb and
      test/t/cases/stream_upstream_server_checks.rb, pass nil. The owner
      decided on 2026-10-29 to fix it in 2.7.3 and to record it as a behavior
      change: 「直していいけどその仕様前提で書いてる人もいるから振る舞いの変更としてちゃんとリリースに書くようにしてね」
      ("fix it, but some people write code that assumes this behavior, so
      record it properly as a behavior change in the release").
    • Why the old behavior could not be kept: an object that is not a String
      has no bytes of a name or of an address to read, so the methods cannot
      give it a meaning; checking the class first is what keeps them from
      reading other memory.
    • What the documentation promised:
      docs/class_and_method/README.md
      described the argument as a string (Nginx::Upstream#new(string),
      Nginx::Upstream#server=(string)) and said nothing about other classes.
  • Affected: code that passes anything but a String to these methods, for
    example nil from a missing key of a Hash, or a Symbol.
  • What to do: pass a String, for example with to_s, and handle a missing
    value before the call.

6. Nginx::Upstream.new and Nginx::Stream::Connection.new find the upstream by its whole name (#652)

  • Before: the two methods compared the name of each upstream {} block with
    the argument only over the length of the argument, case-insensitively, and
    took the first that matched. A name that only started the name of an
    upstream found that upstream: Nginx::Upstream.new("back") found
    upstream backend, and Nginx::Upstream.new("backend") found
    upstream backend_a when that block came first in the configuration.
  • Now: the methods find the upstream whose whole name is the argument,
    compared case-insensitively as nginx compares upstream names. A name that
    only starts the name of an upstream raises RuntimeError
    (<name> not found upstream config), as an unknown name did before.
  • Why it changed:
    • The defect: the comparison was ngx_strncasecmp over the length of the
      argument, in ngx_mrb_upstream_init and ngx_stream_mrb_connection_init.
      It was found when the documentation of #648 was checked against the
      code, and test/t/cases/filter_connection.rb pinned it as the behavior
      of 2.x. The owner decided on 2026-10-29 that
      2.7.3 finds the upstream by its whole name (the option
      "2.7.3で完全一致にする (推奨)", "use the whole name in 2.7.3
      (recommended)"), and approved the change of that expectation (the option
      "変えてよい (推奨)", "it may change (recommended)").
    • Why the old behavior could not be kept: with the prefix, a script that
      named one upstream could get another one, and Nginx::Upstream#server=
      then changed the server of that other upstream.
    • What the documentation promised: the documentation called the argument
      the name of the upstream ("YOUR_UPSTREAM_NAME") and said nothing about a
      part of a name.
  • Affected: scripts that pass a part of the name of an upstream block, and
    scripts that name an upstream whose name starts the name of another
    upstream defined before it.
  • What to do: pass the whole name of the upstream {} block.

7. Nginx::Upstream#server= and Nginx::Stream::Connection#upstream_server= raise for an upstream with a zone (#652)

  • Before: for an upstream {} block with a zone, the two setters changed
    the peer in the shared memory of the zone to point at the memory of the
    worker that called them. With one worker (worker_processes 1) the change
    worked; with more workers, the change was not valid in the other workers,
    as "Not changed by this release" of the Nginx::Upstream#server= entry of
    the 2.7.2 release notes says.
  • Now: both setters raise RuntimeError
    (... does not support an upstream with a zone) before they change
    anything, also with worker_processes 1.
  • Why it changed:
    • The defect: the setters store the name and the address of the server in
      the memory of one worker, which only that worker can read, and point the
      shared peer at it. The owner decided on 2026-10-29 to refuse a zone
      upstream in 2.7.3 (the option "2.7.3で例外にする (推奨)", "raise in 2.7.3
      (recommended)", for question 1 of the proposal
      docs/proposals/archive/upstream-server-setters.md on next).
    • Why the old behavior could not be kept: a change that is valid for every
      worker needs the slab of the zone, and nginx itself replaces the peers of
      a zone upstream when a server has the resolve parameter (nginx 1.27.3
      and later), which an in-place change would work against. Refusing the
      zone case is the change that the 2.x line can make.
    • What the documentation promised: the 2.7.2 release notes called the zone
      case unsupported, and
      docs/class_and_method/README.md
      said that the setters do not check for a zone.
  • Affected: configurations whose scripts call one of the two setters for an
    upstream block with zone, also those with one worker.
  • What to do: remove zone from an upstream block that a script changes
    with these setters; their change applies to one worker either way.

8. An output body filter can send an empty body (#664)

  • Before: when an output body filter ended with an empty body, for example
    after Nginx::Filter.new.output "" (or body = ""), nginx closed the
    connection without sending the response and logged zero size buf in writer at level alert.
  • Now: the filter sends the response with its status, Content-Length: 0
    and no body bytes. For example, return 200 "origin" followed by a filter
    that replaces the body with "" sends an empty 200 response.
  • Why it changed:
    • The defect: ngx_mrb_finalize_body_filter set the memory flag of the
      final buffer even when it contained zero bytes. nginx's writer rejects
      that buffer instead of treating it as the end of the response.
      #574 fixed the same
      defect on next. The existing raw-socket test now checks the status,
      length and body instead of expecting the connection to close without a
      response.
    • Why the old behavior could not be kept: replacing the body with an
      empty string must still send an HTTP response. Keeping the silent close
      would preserve the defect. The owner approved this bounded fix and the
      changed test expectation for 2.7.3 on 2026-10-29.
    • What the documentation promised:
      Nginx::Filter#body=
      says that the response uses the replacement body and its length;
      #output is its alias. It did not exclude an empty string.
  • Affected: output body filters that finish with an empty replacement body.
  • What to do: no script change is needed to send an empty response. Clients
    or monitoring that relied on the silent close or the writer alert must
    accept the HTTP response instead.
  • Not changed by this release: nonempty filter output, content handlers
    that produce no output, and the known connection close after a HEAD
    request with an output body filter keep their existing behavior.

9. Nginx::Upstream#server= and Nginx::Stream::Connection#upstream_server= raise for a string with a NUL byte

  • Before: the two setters accepted some strings with a NUL byte, although no
    server address holds one.
  • Now: Nginx::Upstream#server= raises ArgumentError and
    Nginx::Stream::Connection#upstream_server= raises RuntimeError, the classes
    that each raises for an empty string, with the message invalid upstream server (contains a NUL byte). The server stays as it was.
  • Why it changed:
    • The defect: the difference that "Before" describes.
    • Why the old behavior could not be kept: no server address holds a NUL byte,
      so there is no value that the setters could store for such a string.
    • What the documentation promised:
      docs/class_and_method/README.md
      says what the string may be, and says nothing about a NUL byte.
  • Affected: scripts that give the setters a string with a NUL byte.
  • What to do: give the setters a server address.

セキュリティ

このリリースは、運用者の設定に届くクライアントのリクエストやデータグラムから到達する問題を2件修正します。それぞれにアドバイザリがあります。

  • High — UDPのstreamサーバのクライアントから到達する、streamのNginx::Stream::Async.sleepのuse-after-freeを修正しました(CWE-416)。(GHSA-86wx-fcwx-m3vh)
  • Low — NULバイトを含む文字列をNginx::Upstream#server=やstreamのupstream_server=に渡すと、初期化していないworkerのメモリがupstreamサーバの名前に入りうる問題を修正しました(CWE-200、CWE-908)。(GHSA-8r78-rxqq-5gp5)

どちらも2.7.3で修正済みです。何が変わり何をすべきかは、ノートの「修正」の節(1件目、#645)と項目9(2件目)にあります(アップグレードする設定では、何もする必要はありません)。

アップグレードの前に読む挙動の変更

1. Nginx::SSL::ACME::Dehydrated#auto_cert_deployは、dehydratedの標準エラー出力も読んでCAの利用規約に同意し、同意は1回の呼び出しにつき1回までにします(#636)

  • 変更前:auto-sslのmrbgemの#auto_cert_deployは、dehydratedの標準出力だけを読んでいました。dehydratedの0.5.0以降は、CAの利用規約への同意を求める文を標準エラー出力に書くので、このメソッドはその文を見つけられず、#auto_accept_termsを呼びませんでした。まだ登録していないdehydratedのアカウントでは、dehydratedが止まって証明書が保存されず、ハンドシェイクが失敗しました。証明書が無いので、Nginx::SSL#certificate_data=がTypeErrorを発生させたためです。dehydratedが標準エラー出力に書いた文は、時刻とレベルの無い行のままerror.logに入っていました。同意を求める文を標準出力に書くdehydrated 0.4.0では、このメソッドは#auto_accept_termsを呼んでから自分自身を呼び直し、その回数に上限がありませんでした。登録が失敗すると、次の実行がまた同意を求め、このメソッドはmrubyのスタックが尽きるまで、ハンドシェイクの中でdehydratedを実行し続けました。
  • 変更後:#auto_cert_deployは、dehydratedの標準エラー出力を標準出力にまとめて実行します。そのためのシェルの指定は2>&1です。同意を求める文を見つけると、#auto_accept_termsがdehydrated --register --accept-termsでアカウントを登録し、#auto_cert_deployがdehydratedをもう一度実行して、証明書を取得します。同意は1回の呼び出しにつき1回までです。登録が失敗して2回目の実行がまた同意を求めたときは、dehydratedを2回実行したところで、証明書の無いまま戻ります。--cronが書いた文は、標準エラー出力の分も含めて、このメソッドがNginx::SSL.logで書く[info]の行に入ります。戻り値は、前と同じnilです。
  • 変更の理由:
    • 不具合:このプルリクエストが加えたauto-sslのmrbgemのテストtest/t/cases/auto_ssl.rbを、dehydrated 0.7.2とACMEのテストサーバーのPebbleで動かしたところ、新しいアカウントでは証明書を一度も取得できませんでした。このメソッドは、test/conf/auto-ssl/dehydratedにある版のdehydrated 0.4.0に合わせて書かれていました。0.4.0は、同意を求める文を標準出力に書いていました。また、プルリクエストのレビューで、登録が失敗するとこのメソッドがdehydratedを終わりなく実行することが分かりました。dehydrated 0.7.2は、登録が失敗すると自分で作ったアカウントの鍵を消すので、実行のたびに同意を求めるためです。テストは、外部アカウントの紐付けを求めるPebbleでこれを再現します。
    • 前の挙動を残せなかった理由:このメソッドは、dehydratedが出力した文の中から同意を求める文を探します。標準エラー出力を別にしたままでは、ACME v2を話すどのdehydratedでも、その文を見つけられません。ACME v2を話すのは、dehydratedの0.6.0以降です。Let's Encryptは、2021年にACME v1を止めてから、ACME v2だけを提供しています。同意を求める文を見つけるようになると、上限が無いままでは、登録を断るCAのためにワーカーがハンドシェイクから戻らなくなります。登録を断るのは、外部アカウントの紐付けを求めるCA、障害の起きているCA、新しいアカウントの数を制限しているCAです。
    • ドキュメントが示していた挙動:docs/class_and_method/README.mdは、APIについてmrbgems/auto-ssl/mrblibのスクリプトを参照するよう書いており、dehydratedの出力については何も書いていません。#auto_accept_termsと、#auto_cert_deployの中の判定は、最初の実行で利用規約に同意するためにあります。
  • 影響の範囲:test/conf/auto-ssl/nginx.conf.dehydrated_exampleのように、Nginx::SSL::ACME::Dehydrated#auto_cert_deployを呼ぶTLSのハンドシェイクのハンドラです。error_logのレベルがinfoより上のとき、dehydrated --cronが標準エラー出力に書く文は、エラーも含めて、error.logに出なくなります。例の設定のレベルはnoticeです。
  • 必要な対応:新しいアカウントで証明書を取得するための対応は要りません。dehydrated --cronのエラーをerror.logで見るには、そのサーバーが使うerror_logのレベルをinfoにしてください。1回の呼び出しの中で登録をやり直すことに頼っていたコードでは、後のハンドシェイクでこのメソッドをもう一度呼んでください。その呼び出しが、dehydratedをもう一度実行します。
  • このリリースで変わらない挙動:#auto_accept_termsは、今もdehydrated --register --accept-termsの標準出力だけを読みます。このコマンドが標準エラー出力に書く「Error registering account key」のような文は、今も時刻とレベルの無い行のままerror.logに入ります。

2. Nginx::Async.sleepを呼ぶcontentハンドラは、sleepの後に応答します(#646)

  • 変更前:mruby_content_handler*のコードでNginx::Async.sleepを呼んでも、例外は発生しませんでした。しかし、nginxはそのハンドラを待ちませんでした。リクエストはsleepの時点で終わり、クライアントには応答が届かず、sleepの後のコードは実行されませんでした。接続は閉じられるか、このリクエストに応答しないまま、クライアントの次のリクエストのために開いたままになりました。contentハンドラがsleepするlocationへのサブリクエストは、そのハンドラの出力を受け取りました。Nginx::Async::HTTP.sub_requestが送るサブリクエストが、その例です。しかし、その後にnginxはレベルalertのhttp request count is zeroを書き、その接続はクライアントの次のリクエストに応答しませんでした。
  • 変更後:nginxは、sleepするcontentハンドラを待ちます。sleepの後のコードが実行され、クライアントは、ハンドラがNginx.rputsやNginx.echoで書いた内容か、Nginx.returnで返したステータスを、レスポンスとして受け取ります。これは、sleepしないハンドラと同じです。2回以上sleepするハンドラは、最後のsleepの後に応答します。sleepの後に例外が発生したときは、ほかのハンドラと同じく、リクエストは500を受け取ります。そのようなlocationへのサブリクエストは出力を受け取り、接続はその後も使えます。contentハンドラでは、sleepの後のNginx::Async::HTTP.sub_requestはRuntimeErrorを発生させるので、リクエストは500を受け取ります。そのサブリクエストの後に、nginxがリクエストを終えないためです。2.7.2では、そのコードは実行されませんでした。
  • 変更の理由:
    • 不具合:contentフェーズは、ハンドラのfiberが待っている間にハンドラが返したNGX_DONEで、リクエストをfinalizeしました。そのため、nginxはsleepのタイマーが発火する前にリクエストを解放し、リクエストのcleanupがそのタイマーを消しました。2.7.1のリリースノートは、この件を既知の制限に挙げ、contentハンドラが待てるようにするリリースを予定していました。オーナーは2026-10-04に、contentハンドラで例外を発生させず、Nginx::Async.sleepを使えるようにすると決めました。
    • 前の挙動を残せなかった理由:sleepの後のコードを実行するには、sleepが終わるまでリクエストを残す必要があります。リクエストを残せば、そのリクエストには応答が返ります。不具合を除く別の方法は、logハンドラと同じく、contentハンドラでRuntimeErrorを発生させることでした。この方法では、今は例外なしにこのメソッドを呼んでいるコードが動かなくなります。
    • ドキュメントが示していた挙動:docs/class_and_method/README.mdは、contentハンドラではこのメソッドが例外を発生させず、リクエストはsleepの時点で応答なしに終わると書いていました。また、このメソッドが動く場所として、set、rewrite、accessの各ハンドラを挙げていました。
  • 影響の範囲:Nginx::Async.sleepを呼ぶmruby_content_handlerとmruby_content_handler_codeのコードと、そのようなコードを持つlocationへのサブリクエストです。そのリクエストは、sleepの間は開いたままになり、sleepの後に応答を受け取ります。
  • 必要な対応:sleepの後の応答を期待するコードでは、対応は要りません。sleepで応答なしにリクエストを終わらせることに頼っていたコードには、今は応答が返ります。応答なしに接続を閉じるには、代わりに、ステータス444を表すNginx::HTTP_CLOSEをNginx.returnで返してください。サブリクエストは、contentハンドラのsleepの後でなく、rewriteハンドラかaccessハンドラから送ってください。
  • このリリースで変わらない挙動:Rubyのコードから呼んだNginx.redirectが実行するlocationのcontentハンドラは、今もsleepの時点でリクエストを終え、出力を返しません。Nginx.redirectを呼んだハンドラは呼び出しの後も続き、自分でリクエストに応答することがあります。その場合に、sleepしたハンドラの出力がその応答の後に続くためです。

3. Nginx.redirectが実行するlocationで例外が発生すると、そのlocationのハンドラが終わり、nginxはリクエストを終えます(#646)

  • 変更前:Nginx.redirect "/path"は、/pathのハンドラを実行してから戻ります。/pathのcontentハンドラ、rewriteハンドラ、header filterのような、mrubyのハンドラかフィルタで例外が発生すると、その例外は、Nginx.redirectの呼び出しが発生させたかのように、呼び出したコードに届きました。呼び出しの後のコードは実行されませんでした。呼び出したコードが例外をrescueしなかったときは、呼び出したハンドラが500を返しました。rescueしたときは、クライアントに応答が届きませんでした。どちらの場合も、nginxはリクエストを終えませんでした。接続は、応答の後もクライアントが閉じるまで開いたままで、access logにはそのリクエストの行が書かれず、stub_statusはworkerが終わるまでその接続を有効な接続として数えました。
  • 変更後:例外は、リダイレクトしない場合と同じく、/pathのハンドラを終わらせます。リクエストは、レスポンスをまだ始めていなければ500を受け取ります。Nginx.redirectは戻り、呼び出しの後のコードは、/pathが例外を発生させない場合と同じく実行されます。nginxはリクエストを終え、access logの行を書き、接続を閉じます。Nginx.redirectを呼んだハンドラが、/pathがステータスに残した500で終わると、nginxはそのステータスをもう一度送ろうとして、レベルalertのheader already sentを書きます。これは、リダイレクト先のレスポンスの後にハンドラがステータスを返す場合に、nginxが既に書いている行と同じです。例外のerror.logの行は変わりません。ただし、header filterの例外は、2回でなく1回だけ書かれます。
  • 変更の理由:
    • 不具合:mrubyは、Cから再開したfiberを終わらせる例外を、longjmpで、動いているいちばん内側のmrubyのVMへ渡します。/pathのハンドラは、Nginx.redirectを呼んだハンドラのRubyの呼び出しの中で、自分のfiberとして動きます。そのため、例外は、2つの間にあるnginxの関数を飛び越えました。飛び越えた関数はngx_http_internal_redirectと各フェーズのcheckerで、リクエストを終えるのはこれらの関数です。このプルリクエストのテストtest/t/cases/redirect_to_raising_handler.rbは、開いたまま残る接続を示します。
    • 前の挙動を残せなかった理由:nginxは、例外が飛び越えた関数の中でだけリクエストを終えます。そのため、例外が呼び出したコードに届く限り、リクエストは終わりませんでした。例外を/pathのハンドラで止めると、リクエストは終わり、呼び出したコードは、例外を発生させないlocationへリダイレクトした後と同じく続きます。
    • ドキュメントが示していた挙動:docs/class_and_method/README.mdは、リダイレクト先のlocationがクライアントにレスポンスを返すと書いていましたが、そこで発生する例外については何も書いていませんでした。
  • 影響の範囲:mrubyのハンドラかフィルタが例外を発生させる内部のlocationへ、Nginx.redirectでリダイレクトするコードと、そのような例外をNginx.redirectの周りでrescueしていたコードです。そのようなコードには例外が届かなくなり、呼び出しの後のコードが実行されます。
  • 必要な対応:例外をrescueしていなかったコードでは、対応は要りません。リダイレクト先の失敗に対処するためにNginx.redirectの周りでrescueしていたコードでは、rescueをそのlocationのコードの中へ移してください。
  • このリリースで変わらない挙動:リダイレクト先のrewriteハンドラがNginx::Async.sleepで待っている間に、Nginx.redirectを呼んだハンドラがステータスか例外でリクエストに応答すると、そのrewriteハンドラの出力は、タイマーが発火したときに、接続の上でその応答の後に続きます。

4. streamのセッションは、Nginx::Stream::Async.sleepの後に、コードの結果に応じて先へ進むか終わり、sleepの後の例外は次のセッションを打ち切らなくなります(#651)

  • 変更前:Nginx::Stream::Async.sleepの後にセッションが先へ進んだのは、Nginx::Stream::Connection.stream_statusを既定値のNginx::Stream::DECLINEDのまま残したコードだけでした。コードが例外を発生させるか、ステータスをNginx::Stream::ABORTやNginx::Stream::OKなどの値にすると、nginxはセッションを終えず、先へも進めませんでした。クライアントは、接続を閉じるまで何も受け取らず、セッションはworkerが終わるまで残りました。また、sleepの後の例外は、stream {}ブロックのセッションが共有するmrubyの状態に残りました。workerが次に扱ったセッションは、ブロックのどのserverのセッションでも、自分のコードを実行する前に打ち切られ、error.logには前の例外がそのセッションの行としてもう一度書かれました。
  • 変更後:sleepの後のセッションは、sleepしないコードと同じく先へ進むか終わります。Nginx::Stream::DECLINEDでは次のハンドラへ、Nginx::Stream::OKでは次のフェーズへ進みます。Nginx::Stream::DONEとNginx::Stream::AGAINでは、セッションは待ったままです。例外、Nginx::Stream::ABORT、それ以外のステータスでは、セッションが終わります。sleepの後の例外は、その例外を発生させたセッションの行として1回だけ書かれ、次のセッションは自分のコードを実行します。
  • 変更の理由:
    • 不具合:nginxのaccessフェーズのcheckerは、すぐに戻ったハンドラの結果を処理します。sleepするハンドラはcheckerにNGX_DONEを返し、コードを再開するタイマーは、sleepの後のコードの結果を、NGX_DECLINEDのとき以外は捨てていました。また、例外の後に、sleepしないコードと同じように共有のmrubyの状態から例外を消すこともしませんでした。そのため、次のセッションのngx_stream_mrb_start_fiberは、その例外を自分の例外として読みました。HTTPのハンドラは、2.7.1で同じ消し方をするようになりました(#550)。
    • 前の挙動を残せなかった理由:結果を捨てられたセッションは、終わることも先へ進むこともありません。共有の状態に残った例外は、その例外を発生させていないセッションを終わらせます。nginxのcheckerと同じように結果を処理して、初めてセッションが終わるか先へ進みます。
    • ドキュメントが示していた挙動:docs/class_and_method/README.mdは、Nginx::Stream::Async.sleepをaccessフェーズで使えるメソッドとして、Nginx::Stream::Connection.stream_status=をクライアントを拒むためにNginx::Stream::ABORTを設定するメソッドとして書いていました。sleepの後の結果については、何も書いていませんでした。
  • 影響の範囲:Nginx::Stream::Async.sleepを呼んだ後に例外を発生させるか、Nginx::Stream::Connection.stream_statusをNginx::Stream::DECLINED以外の値にする、mruby_streamとmruby_stream_codeのコードです。そのような例外の後にworkerが次に扱ったstreamのセッションも、影響を受けていました。
  • 必要な対応:クライアントを拒むためにsleepの後でNginx::Stream::ABORTを設定するコードでは、対応は要りません。そのセッションは、今は終わります。sleepの後にNginx::Stream::OKを設定していたコードは、今はproxy_passのような次のフェーズへ進みます。セッションを先へ進めてはならない場合は、代わりにNginx::Stream::ABORTを設定してください。

5. Nginx::UpstreamとNginx::Stream::Connectionは、Stringでない引数にTypeErrorを発生させます(#652)

  • 変更前:Nginx::Upstream.new、Nginx::Upstream#server=、Nginx::Stream::Connection.new、Nginx::Stream::Connection#upstream_server=は、引数のクラスを確かめずに、引数をStringとして読みました。nilを渡すと、2つのsetterはnullポインタを読み、workerのプロセスがsegmentation faultで止まりました。String以外のほかのオブジェクトを渡したときの結果は、mrubyがそのオブジェクトをどう持つかで決まりました。workerが同じように止まるか、メソッドがそのオブジェクトのメモリを文字列のバイトとして読みました。
  • 変更後:4つのメソッドは、Stringでない引数にTypeErrorを発生させます。メッセージは「... cannot be converted to String」です。この検査は、upstreamを探す前と、serverを変える前に行います。Stringと、Stringのサブクラスのインスタンスは、前と同じく使えます。
  • 変更の理由:
    • 不具合:これらのメソッドは、mrb_get_args(mrb, "o", ...)で引数を受け取り、Stringにだけ使えるRSTRING_LENとRSTRING_PTRで読んでいました。場所はsrc/http/ngx_http_mruby_upstream.cとsrc/stream/ngx_stream_mruby_connection.cです。このプルリクエストのテストのtest/t/cases/upstream_server_checks.rbとtest/t/cases/stream_upstream_server_checks.rbは、nilを渡します。オーナーは2026-10-29に、これを2.7.3で直し、挙動の変更として書くと決めました。オーナーの言葉は「直していいけどその仕様前提で書いてる人もいるから振る舞いの変更としてちゃんとリリースに書くようにしてね」です。
    • 前の挙動を残せなかった理由:Stringでないオブジェクトには、読むべき名前やアドレスのバイトがありません。そのため、メソッドはその引数に意味を与えられません。先にクラスを確かめることで、メソッドはほかのメモリを読まなくなります。
    • ドキュメントが示していた挙動:docs/class_and_method/README.mdは、引数を文字列として書いていました。Nginx::Upstream#new(string)とNginx::Upstream#server=(string)がその例です。ほかのクラスについては、何も書いていませんでした。
  • 影響の範囲:これらのメソッドにString以外を渡すコードです。たとえば、Hashに無いキーから得たnilや、Symbolを渡すコードです。
  • 必要な対応:to_sなどでStringを渡し、値が無い場合は呼び出しの前に処理してください。

6. Nginx::Upstream.newとNginx::Stream::Connection.newは、名前全体でupstreamを探します(#652)

  • 変更前:2つのメソッドは、各upstream {}ブロックの名前と引数を、引数の長さの分だけ、大文字と小文字を区別せずに比べ、最初に一致したものを使いました。upstreamの名前の先頭の部分だけの名前でも、そのupstreamが見つかりました。たとえば、Nginx::Upstream.new("back")はupstream backendを見つけました。upstream backend_aが設定の中で先にあると、Nginx::Upstream.new("backend")はupstream backend_aを見つけました。
  • 変更後:メソッドは、名前全体が引数と同じupstreamを探します。比べるときは、nginxがupstreamの名前を比べるのと同じく、大文字と小文字を区別しません。upstreamの名前の先頭の部分だけの名前では、知らない名前と同じく、RuntimeErrorが発生します。メッセージは<name> not found upstream configです。
  • 変更の理由:
    • 不具合:ngx_mrb_upstream_initとngx_stream_mrb_connection_initは、引数の長さの分だけngx_strncasecmpで比べていました。#648のドキュメントをコードと照らしたときに、これが見つかりました。test/t/cases/filter_connection.rbは、これを2.xの挙動として固定していました。オーナーは2026-10-29に、2.7.3で名前全体で探すと決めました。選んだ選択肢は「2.7.3で完全一致にする (推奨)」です。オーナーは、そのテストの期待値の変更も承認しました。選んだ選択肢は「変えてよい (推奨)」です。
    • 前の挙動を残せなかった理由:先頭の部分で一致させると、あるupstreamを指したスクリプトが別のupstreamを受け取ることがあります。その場合は、Nginx::Upstream#server=がその別のupstreamのserverを変えました。
    • ドキュメントが示していた挙動:ドキュメントは、引数をupstreamの名前として書いていました。例は"YOUR_UPSTREAM_NAME"です。名前の一部については、何も書いていませんでした。
  • 影響の範囲:upstream {}ブロックの名前の一部を渡すスクリプトと、先に定義された別のupstreamの名前の先頭と同じ名前のupstreamを指すスクリプトです。
  • 必要な対応:upstream {}ブロックの名前全体を渡してください。

7. Nginx::Upstream#server=とNginx::Stream::Connection#upstream_server=は、zoneのあるupstreamに例外を発生させます(#652)

  • 変更前:zoneのあるupstream {}ブロックでは、2つのsetterは、zoneの共有メモリにあるpeerを、呼んだworkerのメモリを指すように変えました。worker_processes 1でworkerが1つのときは、この変更は動きました。workerが2つ以上のときは、ほかのworkerではこの変更は正しくありませんでした。このことは、2.7.2のリリースノートのNginx::Upstream#server=の項目の「このリリースで変わらない挙動」に書いてあります。
  • 変更後:2つのsetterは、何かを変える前にRuntimeErrorを発生させます。メッセージは... does not support an upstream with a zoneです。worker_processes 1でも同じです。
  • 変更の理由:
    • 不具合:setterは、serverの名前とアドレスを1つのworkerのメモリに置き、共有のpeerをそこへ向けます。そのメモリを読めるのは、そのworkerだけです。オーナーは2026-10-29に、2.7.3でzoneのあるupstreamを拒むと決めました。選んだ選択肢は「2.7.3で例外にする (推奨)」で、nextの構想docs/proposals/archive/upstream-server-setters.mdの問い1への答えです。
    • 前の挙動を残せなかった理由:すべてのworkerで正しい変更には、zoneのslabが要ります。また、serverにresolveのパラメータがあると、nginx 1.27.3以降はnginx自身がzoneのupstreamのpeerを入れ替えます。その場で書き換える変更は、これと衝突します。2.xの系列でできる変更は、zoneの場合を拒むことです。
    • ドキュメントが示していた挙動:2.7.2のリリースノートは、zoneの場合を対応しないものと書いていました。docs/class_and_method/README.mdは、setterがzoneを確かめないと書いていました。
  • 影響の範囲:zoneのあるupstreamブロックに、2つのsetterのどちらかを呼ぶスクリプトを持つ設定です。workerが1つの設定も含みます。
  • 必要な対応:これらのsetterで変えるupstreamブロックから、zoneを外してください。setterの変更は、どちらの場合も1つのworkerにだけ効きます。

8. output body filterで空の本文を送れるようになります(#664)

  • 変更前:output body filterが空の本文で終わると、nginxは応答を送らずに接続を閉じ、レベルalertのzero size buf in writerを書きました。Nginx::Filter.new.output ""かbody = ""で本文を空にした場合が、その例です。
  • 変更後:filterは、応答のステータスとContent-Length: 0を送り、本文のバイトは送りません。たとえば、return 200 "origin"の後でfilterが本文を""に置き換えると、空の200応答を送ります。
  • 変更の理由:
    • 不具合:ngx_mrb_finalize_body_filterは、本文が0バイトでも、最後のバッファにmemoryのフラグを立てていました。nginxのwriterは、そのバッファを応答の終わりとして扱わずに拒否します。nextでは、#574が同じ不具合を直しました。既存のraw socketテストは、応答なしで接続が閉じることではなく、ステータス、長さ、本文を確認するようにしました。
    • 前の挙動を残せなかった理由:本文を空文字列に置き換えても、HTTP応答を送る必要があります。応答なしの切断を残すと、不具合が残ります。オーナーは2026-10-29に、この限定的な修正とテストの期待値変更を2.7.3へ入れると承認しました。
    • ドキュメントが示していた挙動:Nginx::Filter#body=は、置き換えた本文とその長さで応答すると書いています。#outputは、その別名です。空の文字列を除くとは書いていませんでした。
  • 影響の範囲:置き換えた本文が空の状態で終わるoutput body filterです。
  • 必要な対応:空の応答を送るためにスクリプトを変える必要はありません。応答なしの切断やwriterのalertに依存したクライアントや監視は、代わりにHTTP応答を受け取ることに対応してください。
  • このリリースで変わらない挙動:空でないfilter出力、何も出力しないcontentハンドラ、output body filterのあるHEADリクエスト後に接続が閉じる既知の挙動は、そのままです。

9. Nginx::Upstream#server=とNginx::Stream::Connection#upstream_server=は、NULバイトを含む文字列に例外を発生させます

  • 変更前:2つのsetterは、NULバイトを含む文字列のうち、一部の文字列を受け付けました。NULバイトを含むserverのアドレスはありません。
  • 変更後:Nginx::Upstream#server=はArgumentErrorを、Nginx::Stream::Connection#upstream_server=はRuntimeErrorを発生させます。どちらも、空の文字列に発生させるのと同じクラスです。メッセージはinvalid upstream server (contains a NUL byte)です。serverは元のまま残ります。
  • 変更の理由:
    • 不具合:「変更前」に書いた違いです。
    • 前の挙動を残せなかった理由:NULバイトを含むserverのアドレスはありません。このような文字列について、setterが保存できる値はありません。
    • ドキュメントが示していた挙動:docs/class_and_method/README.mdは、文字列に書けるものを書いています。NULバイトについては何も書いていません。
  • 影響の範囲:NULバイトを含む文字列をsetterに渡すスクリプトです。
  • 必要な対応:setterにはserverのアドレスを渡してください。

Performance

Measured with the callgrind comparison (test/perf/compare.sh) against the
tag v2.7.2, 20000 requests per scenario on Ubuntu 22.04 aarch64 (valgrind 3.18.1). Every scenario stays
below the 3% at which the comparison warns: the largest change is
proxy_stream_plain_50 at -0.84% and the largest increase ruby_call_10 at
+0.53%. The security fixes touch code off the request hot path (the string copy in the upstream server setters, which no benchmark scenario calls, and the registration of a stream session's fibers), so they add no measurable per-request work.

Upgrading

Supported nginx versions: the nginx mainline and stable lines; CI builds nginx
1.31.8, 1.30.6, 1.28.3 and 1.26.3. See "Upgrading" in the notes for the
per-entry "What to do".

Full release notes

The complete, per-entry notes are in the repository:
docs/releases/v2.7.3.md
(English) and
docs/releases/v2.7.3.ja.md
(Japanese).