Minimal x86_64 Linux-only file webserver written in assembly language. This page is literate program with all service source code. Project repository and build instructions.

Warning: server is not intented for production use. It may and will wreck you stuff.


Servasm is forking server, each request is processed in separate process. This is how it was done in Mesozoic Era (except we use sendfile(2), which wasn't invented then). And this allows us to make things stupidly simple and take as much leverage from Kernel as possible. We aim for ~1kloc of assembly with comments and spaces.

Main process setups listing socket with few system calls:


Then main process loops on accept(2) system call. For each request it fork(2)s main process and processes request there:.

  1. set alarm(2) to drop very slow clients
  2. recv(2) request headers
  3. check that request is valid (only GET requests are supported)
  4. open(2) requested file
  5. get its size with fstat(2).
  6. write(2) response headers
  7. let kernel send rest with sendfile(2)
  8. close(2) socket and file
  9. exit(2) child

In a case of error we exit process with passing system call result as exit code.

Reference material


Data section keeps all static constants that we might need during server lifetime.

section .data

We are going to use IPv4 and TCP as our transport.

pf_inet:     equ 2
                sock_stream: equ 1

Our server binds to interface. is special ip address that will map to all interfaces on user machine.

sockaddr:    db 0x02, 0x00             ;; AFINET
                db 0x1f, 0x90             ;; PORT 8080
                db 0x00, 0x00, 0x00, 0x00 ;; IP
                addr_len:    equ 128

Requests timeout in 15 second.

request_timeout:   equ 15

Backlog is number of incoming request that kernel will buffer for us, untill we accept(2) them. We set it to 128.

backlog:     equ 128

And we are going to use TCP_CORK option (more on it later)

sol_tcp:     equ 6
                tcp_cork:    equ 3
                on_state:    db  0x01

We store strings as pair of their content and their length following right after message. $ points to current memory address, so current address - start of the string is its length.

startup_error_msg:     db "ERROR: Cannot start server", 10
                startup_error_msg_len: equ $ - startup_error_msg

for incoming request we restrict path to be alphanumeric plus ./

url_whitelist:     db "abcdefghijklmnopqrstuvwxyz"
                db "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789./"
                url_whitelist_len: equ $ - url_whitelist

Lookup tables.

Syscall table for x86-64. For reference look here.

sys_write:        equ 1
                sys_open:         equ 2
                sys_close:        equ 3
                sys_fstat:        equ 5
                sys_alarm:        equ 37
                sys_sendfile:     equ 40
                sys_socket:       equ 41
                sys_accept:       equ 43
                sys_recv:         equ 45
                sys_bind:         equ 49
                sys_listen:       equ 50
                sys_setsockopt:   equ 54
                sys_fork:         equ 57
                sys_exit:         equ 60
                sys_waitid:       equ 247

We build response headers on stack. That means that we need to push strings from last one, for example to build header:

HTTP/1.0 200 OK\r\n
                Server: servasm\r\n
                Content-type: text/html; charset=UTF-8\r\n
                Content-Length: 42\r\n

We will push \n\r24 :htgneL-tnetnoC\n\r8-FTU=tesrahc.... To make this easy we keep pointers to the end of string instead of beggining and use 0x00 byte to mark begining of the string.

We use stack to build headers. string, so all headers are pushed from last character to the first one. We use

\r\n string

db 0x00, 13, 10

Response codes

200 OK

db 0x00, "HTTP/1.0 200 OK", 13, 10

403 Forbidden

db 0x00, "HTTP/1.0 403 Forbidden", 13, 10

404 Not Found

db 0x00, "HTTP/1.0 404 File not found", 13, 10

500 Internal Server Error

db 0x00, "HTTP/1.0 500 OOPSIE", 13, 10

500 Not Implemented

db 0x00, "HTTP/1.0 501 Not Implemented", 13, 10

Mime Types

We use small amout of predefined mime-types backed in source code. And support only utf-8 encoding

db 0x00, "text/plain; charset=UTF-8", 13, 10
                db 0x00, "text/html; charset=UTF-8", 13, 10
                db 0x00, "text/css; charset=UTF-8", 13, 10
                db 0x00, "css/js; charset=UTF-8", 13, 10
                db 0x00, "image/png", 13, 10
                db 0x00, "image/jpeg", 13, 10
                db 0x00, "application/octet-stream", 13, 10

Mime type hash table Each entry has two quad words. first quad word is product of extension ascii codes. For example:

104(h) *  116 (t) *  109 (m) * 108 (l) = 142017408 = 0x8770380

This means that some unknown files can be served with wrong mime-type in case of hash collision. And this is okay. Repeat after me: this is okay.

Second quad word — pointer to the end of matched mime. In the case file type is uknown we serve it with application/octet-stream.

mime_table:     dq 0x18a380,  txt
                dq 0x8770380, html
                dq 0x13fa5b,  css
                dq 0x2f9e,    js
                dq 0x135ce0,  png
                dq 0x12a8a0,  jpg
                dq 0x0,       other



db 0x00, "Content-type: "


db 0x00, "Content-Length: "


db 0x00, "Server: servasm", 13, 10,


BSS section stores data that can be changed during application execution.

section .bss

We will store incoming request in buffer limited to 255 bytes.

buffer:  resb 1025
                buffer_len:  equ 1024
                buffer_read:  resb 8

buffer for result of fstat(2) system call

statbuf: resb 144

Main server socket

server_fd: resb 8

Incoming request socket

client_fd: resb 8

File descriptor to be served

file_fd:   resb 8

Name of requested file

filename: resb 255
                filename_len: resb 8

Size of a file

file_size: resb 8

Mime type for a file

mime_type: resb 8

Source code

section .text

Define etry point

global _start


Our webserver is little more than glue code to few syscalls, actually it's amazing how much can be done only with standard system calls.

Syscalls are made differently for different versions of architectures and operating systems. We restrict ourselvs to x86_64 architecture. To make syscall in x86_64 you need to set rax register to syscall number and rdi, rsi, rdx, r10, r8, r9 registers to parameters 1-6 respectively. Then use syscall instruction to pass control to kernel. syscall result will be stored in rax register. Look here for reference.

Main socket setup

Call socket(2) to create IPv4 TCP socket

mov     rax, sys_socket
                mov     rdi, pf_inet
                mov     rsi, sock_stream
                xor     rdx, rdx

if socket was not created and syscal returned error jump to exit_error

cmp rax, 0
                js .exit_error

If everything is fine, we store result into server_fd.

mov     [server_fd], rax

call setsockopt(2) set TCP_CORK flag to server socket. TCP_CORK flag will prevent sockets from flushing after we write headers. This will allow use to reduce number of packets send, as first packet will include headers and first chunk of served file.

For more info on read blog post or man page.

mov     rax, sys_setsockopt
                mov     rdi, [server_fd]
                mov     rsi, sol_tcp
                mov     rdx, tcp_cork
                mov     r10, on_state
                mov     r8,  8
                cmp rax, 0
                js .exit_error

bind(2) to bind socket to ip, port.

mov     rax, sys_bind
                mov     rdi, [server_fd]
                mov     rsi, sockaddr
                mov     rdx, addr_len
                cmp rax, 0
                js .exit_error

And call listen(2) to start listening for incoming connections. From now kernel will buffer number of incoming requests equal backlog. If backlog is exceeded, requests will be dropped.

mov     rax, sys_listen
                mov     rdi, [server_fd]
                mov     rsi, backlog
                cmp rax, 0
                js .exit_error

Now socket is initialized and ready to serve clients.

Main loop


accept(2) new client from backlog. Call will block untill first client connects.

mov     rax, sys_accept
                mov     rdi, [server_fd]
                xor     rsi, rsi
                xor     rdx, rdx
                cmp rax, 0
                js .exit_error

accept(2) return fd for incoming socket

mov     [client_fd], rax

We process each child in children processes, and when they are exited, they become zombie processes. Kernel keeps their exit code and some other state until parent process gets to it, this is called reaping. We reap all zombie process before processing each request. This means that we can have some between requests. We use waitid(2) to get last process exit code.

                mov     rax, sys_waitid
                mov     rdi, 0
                mov     rsi, 0
                mov     rdx, 0
                mov     r10, 4
                mov     r8,  0

if returned value is >0 it means that we reaped process, and maybe there is more. So we try again. (Errors are ignored here)

cmp rax, 0
                jg .next_process

We process incoming requests one by one, so we need to return to accept(2)ing requests ASAP. So we fork(2) new process to handle client. It will has it's own copy of client fd in client_fd variable. Main process can overwrite this variable safely, as client has own copy.

mov     rax, sys_fork

fork(2) returns negative number in case of error, if it's happens we ragequit from server.

cmp rax, 0
                js  .exit_error

If rax is 0, it means we are inside child, so we jump to serving request

jz  .process_socket

Otherwise we are in the main process, so we close(2) client fd and jmp to accepting new client

mov     rax, sys_close
                mov     rdi, [client_fd]
                cmp rax, 0
                js  .exit_error
                jmp .accept_socket

Processing client


In child process we close(2) server fd

mov     rax, sys_close
                mov     rdi, [server_fd]
                cmp rax, 0
                js  .exit_error

Set alarm(2) to drop slow clients. Kernel will send ALARM signal to child process after request_timeout is elapsed. In happy path we will serve request and exit before alarm is triggered. Otherwise we just exit child process.

mov     rax, sys_alarm
                mov     rdi, request_timeout
                cmp rax, 0
                js  .exit_error

Parse request

call recv(2) to write request to buffer. Our buffer size is limited, but we only need to make few checks and extract filename from it.

mov     rax, sys_recv
                mov     rdi, [client_fd]
                mov     rsi, buffer
                mov     rdx, buffer_len
                xor     r10, r10
                xor     r8,  r8
                xor     r9,  r9
                cmp rax, 0
                js  .exit_error

Our filename extracting algorithm requires that buffer ends with " ".

mov byte [buffer + 1 + rax], " "

Keep bytes read count

mov [buffer_read], rax

For now we accept only GET requests. So we will return 501 error to clients if other request method is used in request.

mov rax, result_unsupported_method
                cmp byte [buffer],     "G"
                jnz  .return_error
                cmp byte [buffer + 1], "E"
                jnz  .return_error
                cmp byte [buffer + 2], "T"
                jnz  .return_error
                cmp byte [buffer + 3], " "
                jnz  .return_error
                cmp byte [buffer + 4], "/"
                jnz  .return_error

call extract_filename procedure to extract filename to filename variable

call extract_filename

check_filenames returns 0 if filename is valid, return 403 otherwise.

call check_filename
                cmp rax, 0
                mov rax, result_forbidden
                jne .return_error

call get_mime to extract mime-type from filename. It will set mime_type variable.

call get_mime

Try to open(2) requested file and put fd to file_fd variable.

mov     rax, sys_open
                mov     rdi, filename
                xor     rsi, rsi ;; no flags
                xor     rdx, rdx ;; readonly
                mov [file_fd], rax

return 404 if open file fails.

cmp rax, 0
                mov rax, result_not_found
                js  .return_error

call fstat(2) to get file info structure and extract file_size from it

mov     rax, sys_fstat
                mov     rdi, [file_fd]
                mov     rsi, statbuf
                cmp rax, 0
                mov rax, result_server_error
                js  .return_error
                mov rax, [statbuf + 48]
                mov [file_size], rax

Write response

after request has been parsed and file found, we start writing response.


read request from socket

call read_full_request

Write headers with write_headers procedure

call write_headers
                cmp rax, 0
                js .exit_error

We use sendfile(2) to make Kernel read data from file_fd and write it to client_fd. we expect sendfile(2) to send whole file at once.

mov     rax, sys_sendfile
                mov     rdi, [client_fd]
                mov     rsi, [file_fd]
                xor     rdx, rdx
                mov     r10, [file_size]
                syscall ;; ignore errors

close(2) client socket

mov     rax, sys_close
                mov     rdi, [client_fd]
                syscall ;; ignore errors

and close(2) file_fd

mov     rax, sys_close
                mov     rdi, [file_fd]
                syscall ;; ignore errors

and finally exit(2) from child process with 0 exit code

xor rax, rax
                jmp .exit

Error handling


Write error response headers and body to client socket

call write_error_response

and close(2) client socket ignoring errors.

mov     rax, sys_close
                mov     rdi, [client_fd]


write(2) error message to stderr

mov     rax, sys_write
                mov     rdi, 2              ; stderr
                mov     rsi, startup_error_msg
                mov     rdx, startup_error_msg_len

set error code to 1

mov     rax, 1


call exit(2) syscall

mov    rdi, rax
                mov    rax, sys_exit


Extract Mime Type

We use filename and filename_len to fill mime_type variable. It will point to end of mime string.

                mov rax, 1
                mov rcx, [filename_len]
                dec rcx

calculate mime_hash using algorithm in Mime Types section.

                xor rdx, rdx
                mov dl, [filename + rcx]
                cmp dl, "."
                je .get_mime_hash_done
                mul rdx
                dec rcx
                cmp rcx, 0
                je .get_mime_hash_done
                jmp .get_mime_hash

                mov rcx, 0

Find pointer to Mime Type using mime_table

                mov r11, [mime_table + rcx]
                cmp r11, rax
                je .get_mime_pointer_done
                cmp r11, 0
                je .get_mime_pointer_done
                add rcx, 16
                jmp .get_mime_get_pointer
                mov rdi, [mime_table + rcx + 8]

and store it to mime_type variable

mov [mime_type], rdi

Write headers

write 200 OK response and some headers to client socket


We will be using stack as buffer for response headers instead of making multiple write calls on socket.

save stack top to temporary register

mov rbp, rsp

push_string uses rcx to keep count of free bytes in current stack top, -1 means no free bytes left and we need to make room for new value.

mov rcx, -1

first we push end of headers (\r\n\r\n)

mov rsi, crnl
                call push_string
                mov rsi, crnl
                call push_string

push Content-Length header

mov rax, [file_size]
                call push_int
                mov rsi, content_length_header
                call push_string

push Content-type header

mov rsi, [mime_type]
                call push_string
                mov rsi, content_type_header
                call push_string

push server name (Server header)

mov rsi, server_header
                call push_string

Push 200 OK response header

mov rsi, result_ok
                call push_string

calculate start headers adress on stack

mov rbx, rcx
                add rbx, rsp
                inc rbx

restore stack state

mov rsp, rbp

calculate length of headers

sub     rbp, rbx

write(2) headers

mov     rax, sys_write
                mov     rdi, [client_fd]
                mov     rsi, rbx
                mov     rdx, rbp


Write error response

write response headers and body to client fd expects rax to point to end of error response code string

                mov r11, rax

read request from socket

call read_full_request

look write_headers method for comments on using push_string.

write end of request

mov rbp, rsp
                mov rcx, -1
                mov rsi, crnl
                call push_string

write request body

mov rsi, r11
                call push_string

write body | headers separator

mov rsi, crnl
                call push_string

write request header

mov rsi, r11
                call push_string

calculate start headers adress on stack

mov rbx, rcx
                add rbx, rsp
                inc rbx

restore stack state

mov rsp, rbp

write(2) request from stack to client socket

mov     rax, sys_write
                mov     rdi, [client_fd]
                mov     rsi, rbx
                sub     rbp, rbx
                dec rbp
                mov     rdx, rbp
                syscall ;; ignore errors


push string

rsi should point to end of string, string should begin with 0x00 byte rcx is used to store byte shift from stack top (0-7), if rcx is -1 it means that additional stack space is required. Funciton will grow stack.

If push string is called multiple times it will form continious string on the stack. For Example, two calls with rcx -1 0x00, "llo" and 0x00, "he" will push "hello" to the stack and set rcx to 2


remove return address from the stack and store it to rdx register

pop   rdx

we use 0x00 to mark begining of passed string.

mov al, 0x00


if we have no free bytes on stack add 8 bytes and change rcx accordingly

cmp rcx, -1
                jne .push_string_write
                push 0
                mov rcx, 7


move string to stack starting from string end until 0x00

dec rsi
                mov rbx, [rsi]
                cmp al, bl
                je .push_string_ret
                mov byte [rsp + rcx], bl
                dec rcx
                jmp   .push_string_next


restore stack

push  rdx

Push int

converts rax to string and calls push_string on it


remove return address from the stack and store it to rdi register.

pop rdi

we convert integer value to sequence of characters with base 10 and push each character with push_string procedure.

mov r8, rax
                mov rax, r8
                xor  rdx, rdx
                mov r11, 10
                div r11
                mov r8, rax
                add dl, 48
                mov rsi, rsp
                sub rsi, 8
                mov byte [rsi - 1], dl
                mov byte [rsi - 2], 0x00
                call push_string
                cmp r8, 0
                je .push_int_ret
                jmp .push_int_next

restore stack

push rdi

Read rest of request

Spec requires us to read full request with headers before we can send response.


We kept amout of read from socket in buffer_read variable.

mov rax, [buffer_read]

We check that last bytes recieved from client were \r\n\r\n

                cmp byte [buffer + rax - 1], 10
                jne .read_more_from_client_socket
                cmp byte [buffer + rax - 2], 13
                jne .read_more_from_client_socket
                cmp byte [buffer + rax - 3], 10
                jne .read_more_from_client_socket
                cmp byte [buffer + rax - 4], 13
                jne .read_more_from_client_socket

if not we recv(2) more data from socket and check buffer again in a loop.

                mov     rax, sys_recv
                mov     rdi, [client_fd]
                mov     rsi, buffer
                mov     rdx, buffer_len
                xor     r10, r10
                xor     r8,  r8
                xor     r9,  r9
                jmp .check_buffer

Extract filename

fills filename and filename_len variables based on request buffer content.


we expect only get request in buffer, so filename should start with fitth character, after GET / string.

mov rsi, buffer + 5
                mov rdi, filename
                xor rcx, rcx

We copy characters from buffer untill we see '?' or ' ' character.

                cmp byte [rsi], " "
                jz .extract_filename_check_index
                cmp byte [rsi], "?"
                jz .extract_filename_check_index
                jmp .extract_filename_next_char

If filename is empty (client requested /), we set filename to be index.html

                mov rcx, rdi
                sub rcx, filename
                cmp rcx, 0
                jnz .extract_filename_done
                mov rax, ""
                mov [filename    ], rax
                mov rax, "ml"
                mov [filename + 8], rax
                mov rcx, 10

                mov [filename_len], rcx

Check filename

Checks that filename is safe to read(2) from filesystem.

                mov rsi, -1

First check filename characters match whitelist

                inc rsi
                mov byte al, [filename + rsi]
                cmp rsi, [filename_len]
                jz .check_filename_whitelist_ok
                mov rdi, url_whitelist
                mov rcx,  url_whitelist_len
                repne scasb
                je .check_filename_whitelist
                jmp .check_filename_return_error

                mov rcx, [filename_len]

First that filename doesn't contain ".." in it.

                dec rcx
                cmp word [filename + rcx], ".."
                je .check_filename_return_error
                cmp rcx, 0
                je .check_filename_return_success
                jmp .check_filename_double_dot

                xor rax, rax

                mov rax, 1

Known issues

  • We use tmp registers to store some global state between procedure calls. This makes recursion impossible and can lead to hidden bugs. Natural way to solve this is to use stack for keeping state between procedure calls, but we use stack to build response string.
  • While simple, forking on each request is not optimal for perfomance. Modern webservers use epoll(2) to process multiple requests in single process.


Copyright (c) 2015 Vladimir Terekhov

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.