# Testing Serial Console

The main aim of this feature is exposing an interactive web-based serial consoles through a web-socket proxy. This page describes how to test it from a devstack environment.

## Setting up a devstack environment

For instructions on how to setup devstack with serial console support enabled see this guide.

## Testing the API

Starting a new instance.

    # cd devstack && . openrc
    # nova boot --flavor 1 --image cirros-0.3.2-x86_64-uec cirros1

Nova provides a command `nova get-serial-console` which will returns a URL with a valid token to connect to the serial console of VMs.

    # nova get-serial-console cirros1
    +--------+-----------------------------------------------------------------+
    | Type   | Url                                                             |
    +--------+-----------------------------------------------------------------+
    | serial | ws://127.0.0.1:6083/?token=5f7854b7-bf3a-41eb-857a-43fc33f0b1ec |
    +--------+-----------------------------------------------------------------+

Currently nova does not provide any client able to connect from an interactive console through a web-socket. A simple client for test purpose can be written with few lines of Python.

    # sudo easy_install ws4py || sudo pip install ws4py
    # cat >> client.py <<EOF
    import sys
    from ws4py.client.threadedclient import WebSocketClient
    class LazyClient(WebSocketClient):
        def run(self):
            try:
                while not self.terminated:
                    try:
                        b = self.sock.recv(4096)
                        while len(b) > 0:
                            # websocket data: opcode + length + data
                            word = b[2:b[1]+2]
                            b = b[b[1]+2:]
                            sys.stdout.buffer.write(word)
                            sys.stdout.flush()
                    except: # socket error expected
                        pass
            finally:
                self.terminate()
    if __name__ == '__main__':
        if len(sys.argv) != 2 or not sys.argv[1].startswith("ws"):
            print("Usage %s: Please use websocket url")
            print("Example: ws://127.0.0.1:6083/?token=xxx")
            exit(1)
        try:
            ws = LazyClient(sys.argv[1], protocols=['binary'])
            ws.connect()
            while True:
                # keyboard event...
                c = sys.stdin.read(1)
                if c:
                    ws.send(c.encode('utf-8'), binary=True)
            ws.run_forever()
        except KeyboardInterrupt:
            ws.close()
    EOF

    # python client.py ws://127.0.0.1:6083/?token=5f7854b7-bf3a-41eb-857a-43fc33f0b1ec
    <enter>
    cirros1 login

this page last updated: 2026-06-08 08:40:45

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug