Repository navigation
ngx_mruby v2.7.3
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 streamupstream_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_deployof 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=raisedTypeErrorfor the
missing certificate. What dehydrated wrote to standard error reached
error.logas 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_termsand 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_deployruns 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_deployruns 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--cronwrites, standard error
included, is in the[info]lines that the method writes with
Nginx::SSL.log. The method returnsnil, 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 inmrbgems/auto-ssl/mrblibfor the API and says nothing
about the output of dehydrated.#auto_accept_termsand the check in
#auto_cert_deployexist to accept the terms of service on the first run.
- The defect: the tests of the auto-ssl mrbgem that this pull request adds
- Affected: TLS handshake handlers that call
Nginx::SSL::ACME::Dehydrated#auto_cert_deploy, as
test/conf/auto-ssl/nginx.conf.dehydrated_exampledoes. With anerror_log
level aboveinfo(the examples usenotice), the messages that
dehydrated --cronwrites to standard error, its errors included, no longer
appear inerror.log. - What to do: nothing to get a certificate with a new account. To see the
errors ofdehydrated --croninerror.log, set the level of the
error_logthat the server uses toinfo. 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_termsstill reads only the
standard output ofdehydrated --register --accept-terms; what that command
writes to standard error, such as "Error registering account key", still
reacheserror.logas raw lines.
2. A content handler that calls Nginx::Async.sleep answers after the sleep (#646)
- Before:
mruby_content_handler*code could callNginx::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 thatNginx::Async::HTTP.sub_request
sends, got the output of that handler, but nginx then logged
http request count is zeroat levelalert, 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 withNginx.rputs
orNginx.echo, or the status that it returns withNginx.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_requestraises aRuntimeErrorin 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 supportsNginx::Async.sleepinstead 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
RuntimeErrorin 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.
- The defect: the content phase finalized the request with the
- Affected:
mruby_content_handlerandmruby_content_handler_codecode
that callsNginx::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) withNginx.returninstead. 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
thatNginx.redirectruns from Ruby code still ends the request at the
sleep, without its output. The handler that calledNginx.redirectgoes 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/pathbefore it
returns. When an mruby handler or filter of/pathraised, for example its
content handler, rewrite handler or header filter, the exception reached
the code that calledNginx.redirectas 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
/pathas it does without the
redirect, and the request gets 500 unless its response was already
started.Nginx.redirectreturns, and the code after it runs, as when
/pathdoes not raise. nginx finishes the request, writes its access log
line and closes the connection. When the handler that called
Nginx.redirectends with the 500 that/pathleft in the status, nginx
tries to send that status again and logsheader already sentat level
alert, as it already does when a handler returns a status after the
response of the redirect target. Theerror.loglines 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/pathruns
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_redirectand 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/pathlets 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.
- The defect: mruby passes the exception that ends a fiber resumed from C
- Affected: code that calls
Nginx.redirectwith an internal location whose
mruby handlers or filters raise, and code that rescued such an exception
aroundNginx.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 aroundNginx.redirectto react to a failure of the redirect
target moves therescueinto 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 inNginx::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_statusatNginx::Stream::DECLINED, the
default, let the session go on. When the code raised, or set the status to
Nginx::Stream::ABORT,Nginx::Stream::OKor 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::DECLINEDgoes on with the next handler,
Nginx::Stream::OKwith the next phase,Nginx::Stream::DONEand
Nginx::Stream::AGAINleave the session waiting, and an exception,
Nginx::Stream::ABORTor 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 returnsNGX_DONE
to it, and the timer that resumes the code dropped the result of the code
after the sleep, except forNGX_DECLINED. After an exception it did not
clear the exception from the shared mruby state either, as the code
without the sleep does, andngx_stream_mrb_start_fiberof 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
documentedNginx::Stream::Async.sleepfor the access phase and
Nginx::Stream::Connection.stream_status=withNginx::Stream::ABORTto
deny a client, and said nothing about the result after the sleep.
- The defect: nginx's checker of the access phase handles the result of a
- Affected:
mruby_streamandmruby_stream_codecode that calls
Nginx::Stream::Async.sleepand then raises, or sets
Nginx::Stream::Connection.stream_statusto 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::ABORTafter the
sleep to deny a client: the session now ends. Code that set
Nginx::Stream::OKafter the sleep now goes on with the next phase, for
exampleproxy_pass; setNginx::Stream::ABORTinstead 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.newandNginx::Stream::Connection#upstream_server=
read their argument as a String without checking its class. Withnil,
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 withRSTRING_LENandRSTRING_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.rband
test/t/cases/stream_upstream_server_checks.rb, passnil. 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.
- The defect: the methods took the argument with
- Affected: code that passes anything but a String to these methods, for
examplenilfrom 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, andNginx::Upstream.new("backend")found
upstream backend_awhen 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 raisesRuntimeError
(<name> not found upstream config), as an unknown name did before. - Why it changed:
- The defect: the comparison was
ngx_strncasecmpover the length of the
argument, inngx_mrb_upstream_initandngx_stream_mrb_connection_init.
It was found when the documentation of #648 was checked against the
code, andtest/t/cases/filter_connection.rbpinned 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, andNginx::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.
- The defect: the comparison was
- 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 azone, 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 theNginx::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 withworker_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.mdonnext). - 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 theresolveparameter (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.
- The defect: the setters store the name and the address of the server in
- Affected: configurations whose scripts call one of the two setters for an
upstream block withzone, also those with one worker. - What to do: remove
zonefrom 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
afterNginx::Filter.new.output ""(orbody = ""), nginx closed the
connection without sending the response and loggedzero size buf in writerat levelalert. - 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_filterset thememoryflag 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 onnext. 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;
#outputis its alias. It did not exclude an empty string.
- The defect:
- 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=raisesArgumentErrorand
Nginx::Stream::Connection#upstream_server=raisesRuntimeError, the classes
that each raises for an empty string, with the messageinvalid 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の中の判定は、最初の実行で利用規約に同意するためにあります。
- 不具合:このプルリクエストが加えたauto-sslのmrbgemのテスト
- 影響の範囲:
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の各ハンドラを挙げていました。
- 不具合:contentフェーズは、ハンドラのfiberが待っている間にハンドラが返した
- 影響の範囲:
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は、Cから再開したfiberを終わらせる例外を、longjmpで、動いているいちばん内側のmrubyのVMへ渡します。
- 影響の範囲: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のaccessフェーズのcheckerは、すぐに戻ったハンドラの結果を処理します。sleepするハンドラはcheckerに
- 影響の範囲:
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を確かめないと書いていました。
- 不具合:setterは、serverの名前とアドレスを1つのworkerのメモリに置き、共有のpeerをそこへ向けます。そのメモリを読めるのは、そのworkerだけです。オーナーは2026-10-29に、2.7.3でzoneのあるupstreamを拒むと決めました。選んだ選択肢は「2.7.3で例外にする (推奨)」で、nextの構想
- 影響の範囲:
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).