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

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

screenshot 1

It’s usually in this path.

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

1
resty -V

screenshot 3

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

1
dnf list installed openresty-resty

screenshot 4

Because it’s not in the openresty main package.

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

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

screenshot 6

Note the -e option.

Or run a Lua script on the terminal.

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

screenshot 8

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

Nonblocking I/O is also possible here.

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

screenshot 10

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

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

screenshot 11

Or using light threads.

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

screenshot 12

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

1
2
mkdir lua/
vim lua/test.lua

The lua/test.lua file looks like this:

1
2
3
4
5
local _M = {}

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

return _M

screenshot 13

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

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

screenshot 14

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

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

screenshot 15

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.

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

screenshot 17

This module is for running abitrary shell commands nonblockingly.

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

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

screenshot 19

Multiple shared dictionaries can be defined this way.

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

screenshot 20

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

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

screenshot 21

We can also play with LuaJIT’s JIT compiler.

Let’s create a hot Lua script.

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

screenshot 23

And then disable the JIT compiler altogether.

1
time resty -joff bench.lua

screenshot 24

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

1
time resty bench.lua

screenshot 25

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

1
resty -jv bench.lua

screenshot 26

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

1
resty -jdump bench.lua

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

1
resty -h

Or refer to its documentation via the restydoc utility.

1
restydoc resty-cli

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

1
dnf list installed openresty-doc

screenshot 30

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

About This Article and Associated Video

This article and its associated video are both generated automatically from a simple screenplay file.

About The Author

Yichun Zhang is the creator of the OpenResty® open source project. He is also the founder and CEO of the OpenResty Inc. company. He contributed a dozen open source Nginx 3rd-party modules, quite some Nginx and LuaJIT core patches, and designed the OpenResty XRay platform.

Translations

We will provide a Chinese translation for this article on blog.openresty.com.cn. We also welcome interested readers to contribute translations in other natural languages as long as the full article is translated without any omissions. We thank them in advance.

We are hiring

We always welcome talented and enthusiastic engineers to join our team at OpenResty Inc. to explore various open source software’s internals and build powerful analyzers and visualizers for real world applications built atop the open source software. If you are interested, please send your resume to talents@openresty.com . Thank you!