Check out how OpenResty XRay helps organizations troubleshoot issues and optimize the performance of their applications.

Learn More LIVE DEMO

In this tutroial, we will demonstrate how to use the resty command-line utility shipped with OpenResty.

cd ~
export PATH=/usr/local/openresty/bin:$PATH
which resty

It’s usually in this path.

We can check its version number with the -V option.

resty -V

If you install OpenResty using our pre-built binary packages for Linux, then you should install the openresty-resty package.

dnf list installed openresty-resty

Because it’s not in the openresty main package.

It’s much easier to do “hello world” using a resty command, for example.

resty -e 'print("Hello World")'

Note the -e option.

Or run a Lua script on the terminal.

echo 'print("Hello World")' > hello.lua
cat hello.lua
resty hello.lua

So it is also a great way to write new command-line applications using OpenResty.

Nonblocking I/O is also possible here.

time resty -e 'ngx.sleep(1) ngx.say("done")'

Let’s connect to openresty.com’s 443 port using the cosocket API.

resty -e 'local sock = ngx.socket.tcp() print(sock:connect("openresty.com", 443))'

Or using light threads.

resty -e 'ngx.thread.wait(ngx.thread.spawn(function () print("in thread!") end))'

You can also use Lua modules easily. Let’s create a test module.

mkdir lua/
vim lua/test.lua

The lua/test.lua file looks like this:

local _M = {}

function _M.hello() print("Hello") end

return _M

And then we use the -I option to add the lua/ directory to the Lua module search paths.

resty -I lua/ -e 'require "test".hello()'

Without the -I option, it won’t find it.

resty -e 'require "test".hello()'

This is because the lua/ directory is not in the Lua module search paths by default.

Standard Lua modules can be loaded directly, like resty.shell.

resty -e 'local ok, stdout = require "resty.shell".run([[echo ok]]) print(stdout)'

This module is for running abitrary shell commands nonblockingly.

We can also define lua shared memory dictionaries via the --shdict option.

resty --shdict 'dogs 10m' -e 'print(ngx.shared.dogs:set("age", 11))'

Multiple shared dictionaries can be defined this way.

resty --shdict 'dogs 7m' --shdict 'cats 5m' -e 'print(ngx.shared.dogs, " ", ngx.shared.cats)'

It can also be handy to inject custom nginx configuration snippets.

resty --http-conf 'lua_regex_match_limit 102400;' -e 'print "ok"'

We can also play with LuaJIT’s JIT compiler.

Let’s create a hot Lua script.

echo 'local a = 0 for i = 1, 1e8 do a = a + 1 end print(a)' > bench.lua
cat bench.lua

And then disable the JIT compiler altogether.

time resty -joff bench.lua

For comparison, we can check how much faster when we enable the JIT compiler.

time resty bench.lua

Or we can check the compiled Lua code paths, or “traces”, with the -jv option.

resty -jv bench.lua

Or with even more details like the compiled bytecode dump, IR code dump, as well as machine code dump.

resty -jdump bench.lua

You can always find all the supported features via the -h option.

resty -h

Or refer to its documentation via the restydoc utility.

restydoc resty-cli

If you install openresty through our pre-built binary packages, then you should install the openresty-doc or openresty-restydoc package.

dnf list installed openresty-doc

We will have a closer look at the restydoc utility in another dedicated video tutorial.

About The Author

Yichun Zhang (Github handle: agentzh), is the original creator of the OpenResty^® open-source project and the CEO of OpenResty Inc..

Yichun is one of the earliest advocates and leaders of “open-source technology”. He worked at many internationally renowned tech companies, such as Cloudflare, Yahoo!. He is a pioneer of “edge computing”, “dynamic tracing” and “machine coding”, with over 22 years of programming and 16 years of open source experience. Yichun is well-known in the open-source space as the project leader of OpenResty^®, adopted by more than 40 million global website domains.

OpenResty Inc., the enterprise software start-up founded by Yichun in 2017, has customers from some of the biggest companies in the world. Its flagship product, OpenResty XRay, is a non-invasive profiling and troubleshooting tool that significantly enhances and utilizes dynamic tracing technology. And its OpenResty Edge product is a powerful distributed traffic management and private CDN software product.

As an avid open-source contributor, Yichun has contributed more than a million lines of code to numerous open-source projects, including Linux kernel, Nginx, LuaJIT, GDB, SystemTap, LLVM, Perl, etc. He has also authored more than 60 open-source software libraries.