DOCSEARCHbyAlgolia
Submit Docs

MicroSocks Documentation

repository·master·Indexed 24 days ago

https://github.com/rofl0r/microsocks

A lightweight, multithreaded SOCKS5 server designed for tunneling connections on remote machines with low resource consumption. It supports IPv4, IPv6, DNS, and TCP, with authentication modes including none, password, and a one-time 'auth_once' whitelist mode. The documentation covers command-line configuration, usage with curl and Firefox, and C API functions such as server_setup(), server_waitclient(), and address resolution utilities.

Tokens
1.5K
Snippets
5
Records
12
Agent score
80%

What's inside MicroSocks

  2. Understand the sockaddr_union and client structures

    master

    The library uses a custom union to abstract over IPv4 and IPv6 addresses, and a client struct to manage connection state.

    union sockaddr_union Supports both IPv4 and IPv6:

    • v4: struct sockaddr_in
    • v6: struct sockaddr_in6

    struct client Represents an active connection:

    • addr: The union sockaddr_union containing the client's address.
    • fd: The file descriptor for the client connection.

    struct server Represents the listening server instance:

    • fd: The file descriptor for the listening socket.

  3. Troubleshoot MicroSocks segfaults

    master

    If you experience segfaults, it may be due to the thread stack size being too small for your platform. MicroSocks uses the smallest safe thread stack size to minimize memory usage.

    Solution: Try raising the THREAD_STACK_SIZE in sockssrv.c for your platform in increments of 4KB. If this resolves the issue, it is recommended to file a pull request.

  4. How to use auth_once mode with curl and Firefox

    master

    To use auth_once mode (-1), you must first authenticate once using a tool that supports user/password authentication (like curl). Once successful, the IP address is whitelisted, allowing other programs (like Firefox) to use the proxy without credentials.

    Example workflow:

    1. Start MicroSocks with the -1 flag.
    2. Authenticate using curl:
    curl --socks5 user:password@listenip:port anyurl
    1. Use Firefox or other clients without credentials.

  6. Configure MicroSocks via command line options

    master

    All MicroSocks arguments are optional. Use the following flags to configure the server behavior:

    • -1: Activates auth_once mode. Once a specific IP address authenticates successfully with a username/password, it is added to a whitelist and can subsequently use the proxy without authentication. This is useful for applications like Firefox that may not support user/password authentication.
    • -q: Disables logging.
    • -i <listenip>: Specifies the IP address the server listens on (default is 0.0.0.0).
    • -p <port>: Specifies the port to listen on (default is 1080).
    • -u <user>: Specifies the username for password authentication.
    • -P <passw>: Specifies the password for password authentication.
    • -b <bindaddr>: Specifies which IP outgoing connections are bound to.
    • -w <whitelist>: Specifies a comma-separated whitelist of IP addresses that may use the proxy without user/pass authentication (e.g., -w 127.0.0.1,192.168.1.1,::1).
    microsocks -1 -q -i listenip -p port -u user -P passw -b bindaddr -w wl

  7. Resolve hostnames and ports

    master

    MicroSocks provides utility functions to resolve hostnames and ports into address structures suitable for networking operations.

    Functions:

    • int resolve(const char *host, unsigned short port, struct addrinfo** addr): Resolves a host and port into an addrinfo pointer.
    • int resolve_sa(const char *host, unsigned short port, union sockaddr_union *res): Resolves a host and port directly into a union sockaddr_union structure.
    • int bindtoip(int fd, union sockaddr_union *bindaddr): Binds a socket file descriptor to a specific union sockaddr_union address.

  8. Initialize the SOCKS5 server with server_setup()

    master

    To start the MicroSocks server, use server_setup(). This function resolves the provided listenip and port, creates a socket, sets SO_REUSEADDR, binds to the address, and begins listening.

    Returns:

    • 0 on success.
    • -1 if address resolution fails.
    • -2 if no socket could be bound to the requested address.
    • -3 if the listen() call fails.

  9. Initialize and run the SOCKS5 server

    master

    To set up a SOCKS5 server instance, use server_setup to bind the server to a specific IP address and port. Once initialized, use server_waitclient to wait for and handle incoming client connections.

    Note that server_setup requires a string for the listenip (e.g., "0.0.0.0" for all IPv4 interfaces) and an unsigned short for the port.

  10. Accept incoming client connections with server_waitclient()

    master

    Once the server is set up, use server_waitclient() to wait for and accept a new client connection. This function populates the fd and addr fields of the provided client structure.

    Returns:

    • The client file descriptor on success.
    • -1 if accept() fails.

  11. Use server_setup to bind the server

    master

    The server_setup function initializes a struct server by binding it to a specified IP address and port.

    Signature: int server_setup(struct server *server, const char* listenip, unsigned short port)

    Parameters:

    • server: A pointer to a struct server instance to be initialized.
    • listenip: A string representing the IP address to listen on (e.g., "127.0.0.1" or "0.0.0.0").
    • port: The port number to bind to.

    Returns:

    • int: Returns 0 on success, or an error code on failure.
    int server_setup(struct server *server, const char* listenip, unsigned short port);

  12. Use server_waitclient to accept connections

    master

    The server_waitclient function blocks until a new client connects to the server and populates a struct client with connection details.

    Signature: int server_waitclient(struct server *server, struct client* client)

    Parameters:

    • server: A pointer to the initialized struct server.
    • client: A pointer to a struct client which will be populated with the client's file descriptor (fd) and address (addr).

    Returns:

    • int: Returns 0 on success, or an error code on failure.
    int server_waitclient(struct server *server, struct client* client);