Sonic is a PHP CLI (command line) executable that is able to thread (or rotate instances of) services via custom loaded modules. the daemon itself is function orientated which handles forks (or sequential instances) of configured sonic-stream modules which are object orientated. stream modules can be either standalone or standalone with a preloaded listening socket connection. there are two example plug-in sonic stream modules packaged with the daemon for test and learning purposes. there are also currently 4 separate (but branded) stream module projects that demonstrate the generic polymorphic capabilities of Sonic. ie.

• exec, drop shell executer
• ping, echo icmp ping-pong
• src_relay, socket relay with source address binding
• www, HTTP+PHP/CLI (pseudo CGI emulated) WWW server

in a nutshell, if you want a PHP scriptable, thread capable cross-platform server type daemon then Sonic is the droid youre looking for.

Sonic can be useful for a few things, eg. anything you need forked, or forked with socket handling. eg. you could use the two packaged example stream modules (local and remote) to start your own cron and net-cat replacement (for insanities sake).

a PHP CLI enviroment installed, setup and a reason. There is a *nix shell and winblowz batch confgiuration script to help loading the main Sonic executable (which may need some tweaking on custom Sonic/PHP installs).

Unpack then check the environment configuration script in the bin directory, the Sonic ini configuration file in the conf directory, then run.

-v 3
Run Sonic daemon with verbose output sent to log
$ bin/sonic-daemon.sh -v 3 > /path/to/log/file.txt

-q
Launch Sonic daemon into the background process (no logging)
$ bin/sonic-daemon.sh -q &

--tcp_echo
Run Sonic daemon with debug output of tcp stream sent to self on port 1234. mirror input back to server on same socket
$ bin/sonic-daemon.sh -S t1 --s-t1-stream=remote --s-t1-port=1234 --s-t1-tcp_echo=On

--service-NAME-socket_protocol SOL_UDP
Run Sonic daemon with raw output of udp stream sent to self on port 1234
$ bin/sonic-daemon.sh -v 3 -S u1 --s-u1-stream=remote --s-u1-socket_type=SOCK_DGRAM --s-u1-socket_protocol=udp --s-u1-port=1234

-S
Launch Sonic with ini supplied WWW server and runtime supplied source relay setup (temporary virtual hosting)
$ cat /etc/sonic/conf/sonic.ini [SONIC_DAEMON] ;services = www1 service-www1-stream = www service-www1-max = 10 service-www1-ip = 127.0.0.1 service-www1-port = 80 service-www1-document_root = /var/www $ $ bin/sonic-daemon.sh -S www1,v1,v2 \ --s-v1-stream=src_relay \ --s-v1-max=3 \ --s-v1-ip=72.14.254.1 \ --s-v1-port=80 \ --s-v1-dst_host=127.0.0.1 \ --s-v1-dst_port=80 \ \ --s-v2-stream=src_relay \ --s-v2-max=3 \ --s-v2-ip=72.14.254.2 \ --s-v2-port=80 \ --s-v2-dst_host=127.0.0.1 \ --s-v2-dst_port=80
--stream exec --exec stunnel --stream www --port 80 --stunnel_log path/to/stunnel.log
stunnel port 443 (and forward) and sonic port 80
stunnel4 in -> 0.0.0.0:443 -> out -> 0.0.0.0:80
sonic-w1 in -> 0.0.0.0:80 -> out -> peername
Run Sonic daemon initating stunnel pairing with www stream on port 80 as a SSL web-server
$ bin/sonic-daemon.sh -S e1,w1 \ --s-e1-stream=exec \ "--s-e1-exec=\"/usr/bin/stunnel -d 443 -r 80 -o ./stunnel-exec1.log -f\"" \ --s-w1-stream=www --s-w1-port=80 --s-w1-document_root=. \ --s-w1-stunnel_log=./stunnel-exec1.log (different 'Host:') Run Sonic daemon initating stunnel pairing with www stream on host 192.168.0.22 via non-stantard port 8081 and as a SSL web-server on non-standard port 8082 with virtual host setup for single address 192.168.0.22:8082
$ bin/sonic-daemon.sh -S e1,w1 \ --s-e1-stream=exec \ "--s-e1-exec=\"/usr/bin/stunnel -d 8082 -r 192.168.0.22:8081 -o ./stunnel-exec1.log -f\"" \ --s-w1-stream=www --s-w1-ip=192.168.0.22 --s-w1-port=8081 --s-w1-document_root=. \ --s-w1-stunnel_log=./stunnel-exec1.log \ --s-w1-vhosts=v1 --s-w1-v1-host=192.168.0.22:8082 --s-w1-v1-document_root=.
--stream src_relay --tcp_echo
streamming debug/sanity/dump/mux test
in -> 192.168.0.10:1234 -> 192.168.0.10:2234 -> out -> 192.168.0.50:1234
Run tcp echo on self port 2234. take inbound udp stream from server sending on port 1234, pass stream (with source stamp 192.168.0.10) via tcp to self running tcp_echo on port 2234. then push tcp_echo reply via udp stream (with source stamp 192.168.0.10) to 192.168.0.50 on port 1234.
$ bin/sonic-daemon.sh -S u1,r1 \ --s-u1-stream=src_relay \ --s-u1-socket_type=SOCK_DGRAM \ --s-u1-socket_protocol=udp \ --s-u1-port=1234 \ --s-u1-src_ip=192.168.0.10 \ --s-u1-relay_socket_type=SOCK_STREAM \ --s-u1-relay_socket_protocol=tcp \ --s-u1-dst_host=0.0.0.0 \ --s-u1-dst_port=2234 \ --s-u1-mux_socket_type=SOCK_DGRAM \ --s-u1-mux_socket_protocol=udp \ --s-u1-mux_src_ip=192.168.0.10 \ --s-u1-mux_host=192.168.0.50 \ --s-u1-mux_port=1234 \ \ --s-r1-stream=remote \ --s-r1-port=2234 \ --s-r1-tcp_echo=true

This was written circa 2004, dusted off and taken off the shelf in 2008. If anyone wants to get carried away with the daemon list below, or some stream modules eg. proxy, webserver, proxy relay, etc-server please let me know, i will probably release some useful stream modules myself eventually. There is a download to unpack inside the main Sonic directory, for anyone using winblowz and cygwin without PHP installed. *winblowz*NB: only the cygwin version of PHP is threadable via pthreads.

TODO (daemon)

• any bugfixes
• (almost dont care) socket_options can only set scalars
• (not sure = dont care) optional update waittime for IPC, but can introduce timed DDOS
• (dont care) send log to centralised stream, IPC, or fork it to remove ques and reduce any timeshifts further (NB, buffer mode)
• replace ! messages with error_log and option to repeat in STDOUT (eg. logging purposes)?

TODO (INC.)

• continue place holders for strm/stream_socket
• multipart post

INFO. / DEV

• releases currently FROZEN since 2008-09-11
• notes current as of versions
  • 0.2.27 sonic.inc
  • 0.2.39 sonic-daemon.php
  • 0.2.27 ss.www.php
• stunnel management via exec stream
• SSL client peername via stunnel log parse (stream dev)
  NB, if you have stunnel forwarding log parse enabled, with any connections to the the original sonic port (without being forwared by stunnel ie. no log parse), there will be a DELAY of max wait time in useconds BY usec increments.
  • --s-SERV_NAME-stunnel_log=path/to/stunnel.log
  • --s-SERV_NAME-stunnel_usec=600
  • --s-SERV_NAME-stunnel_usec_wait_time=2000
  • --s-SERV_NAME-stunnel_log_lines=25
  • --s-SERV_NAME-stunnel_force=On
  sonic socket listen streams/services that support stunnel peername
  • remote
  • src_relay
  • www
  • ssa
• IPC via plugin handlers
  • http - eg. http://127.0.0.1:3438/?op=IPC
• internal logging available only when output set to 'buffer', log is lock write safe (so there might be DELAYs ie. a que to write, when threads are enabled). also note, that seeing there is some caching and therefore delay before actual output to STDOUT or log, timestamps may be shifted from there original order
• log management via sonic daemon + stream
  NB, --s-SERV_NAME-verbose, --verbose > 998 will echo buffer tick (not in actual buffer)
  NB, --s-SERV_NAME-verbose, --verbose > 9998 will echo log write hit (not in actual buffer)
  deamon
  • --output=buffer|flush
  • --log=path/or/file/to/main/log
  stream
  • --s-SERV_NAME-thread_out=buffer|flush
  • --s-SERV_NAME-thread_buffer_quiet=On|Off
  • --s-SERV_NAME-thread_log=path/or/file/to/service/log
• php4 & php5 compatible
  • aggregate functions removed since sonic daemon version 0.2.4
• other 3rd party sonic stream modules
  • SSA - SSL SMTP Agent
• tested platforms
  • linux       x32/64bit, ubuntu, ubuntu+debian under openvz
  • windows x32/64bit, XP
• daemon reserved globals (daemon dev)
  DMZ
  • (threaded parent scope safe, rotate unsafe) $_SONIC
  below are in threaded/forked only global scope but parent scope safe
  • $_sd_thread_handler_lock
  • $_sd_threads
  • $_sd_threads_service
  • $_sd_threads_service_active
  • $_sd_threads_shutdown
  below are under protected ..main() scope
  • $SONIC_ARG
  • $quiet, $verbose
  • $_sd_config
  • $_sd_services
  • $_sd_strm_obj
  IPC related below are under protected ..main() scope
  • $_sd_ipc_service_config
  • $_sd_is_time_check
  • $_sd_is_endpoint_connected
  • $_sd_is_wait
  • $_sd_is_wait_time
  • $__sd_is_buf
  • $_sd_is_buf
  • $_sd_is_sopt_rt
  • $_sd_is_read
  • $_sd_is_write
  • $_sd_is_except
  • $_sd_is_changed_sockets
  • $_sd_is_fin
  • $_sd_is_out
  thread related below are under protected ..main() scope
  • $_sd_threaded
  • (threaded only) $_sd_threaded_pid
  • (threaded only) $_sd_threads_total
• daemon reserved functions
  DMZ
  • array sonic_daemon_load_config_IPC(array $config, $opts = array("fatal" => false, "quiet" => true))
  • bool sonic_daemon_load_IPC(array &$ipc, $opts = array("fatal" => false, "quiet" => true))
  • array(array, int) sonic_daemon_load_config_services(array $config, $opts = array("fatal" => false, "quiet" => true))
  • bool sonic_daemon_load_services(array &$services, $opts = array("fatal" => false, "quiet" => true))
  • array sonic_daemon_thread_info($opts = array("quiet" => false, "verbose" => 0))
  • int sonic_daemon_thread_kill($pids = array(), $opts = array("quiet" => true, "verbose" => 0))
  internal
  • sonic_daemon_main()
  • sonic_daemon_thread_handler($sig = NULL)
  • sonic_daemon_thread_shutdown($sig = NULL)
• more API Documentation

PHP Ping

..no and den

--stream ping --host localhost
Run Sonic daemon and ping localhost
$ bin/sonic-daemon.sh -S p1 --s-p1-stream=ping --s-p1-host=127.0.0.1

• alpha
• no ttl (no access to IP header, etc)
• no and then..

The proxy relay connects to the destination server/end-point on behalf of the connected client. the proxy relay can also have all or one of its interfaces/ip-addresses bound to the connection(s) ie. allows alternate source addressing. if the server end-point is a tcp connection, the relay can also re-route the return replies.

STREAM MAP - unicast. multicast. asymmetric socket I/O (multiplex/mux) sock_in src_relay sock_out | | | | | | | | | | | | --> | udp/ | ----> |[src_any]| ----> | udp/ | ->- | tcp | | mux_any | | tcp | ip:port | | | | | | dst_host:dst_port | | | | | | <-- | tcp/ | <---- |[mux_tcp]| <---- | tcp | <-- | udp | | | | | mux_host:mux_port | | | | | | [ tcp-1 ] <<---->> [ src relay ] <<--->> [ tcp-2 ] [ udp / ] [ tcp-1 ] >>--. `>> [ ] [ src relay ] <<--->> [ tcp-2 ] [ udp / ] ,<< [ ] [ tcp-3 ] <<--' [ tcp / ] [ udp-1 ] >>---->> [ src relay ] >>--->> [ udp-2 ]

; proxy relay: src_relay.ini ; or merged into default main conf sonic.ini ;// ; set services to load services = src1, src2 ; service src1 - sonic generic service-src1-stream = src_relay service-src1-max = 5 service-src1-ip = 127.0.0.1 service-src1-port = 8081 ; service src1 - stream module specific service-src1-src_ip = 0.0.0.0 service-src1-dst_host = proxy1.destination.com service-src1-dst_port = 8080 ; service src2 service-src2-stream = src_relay service-src2-max = 5 service-src2-ip = 127.0.0.1 service-src2-port = 8082 service-src2-src_ip = 0.0.0.0 service-src2-dst_host = proxy2.destination.com service-src2-dst_port = 8080

--stream src_relay --port 8022 --dst_host localhost --dst_port 22
port open and forward
in -> 0.0.0.0:8022 -> out -> 127.0.0.1:22
Run Sonic daemon exporting local only sshd service port on 8022
$ bin/sonic-daemon.sh -q -S s1 --s-s1-stream=src_relay --s-s1-port=8022 --s-s1-dst_host=127.0.0.1 --s-s1-dst_port=22

--stream src_relay --port 1234 --dst_host broadcast --dst_port 1235
port open and forward
in -> 0.0.0.0:1234 -> out -> 192.168.0.255:1235
Run Sonic daemon re-routing incomming stream on port 1234 to broadcast range on port 1235
$ bin/sonic-daemon.sh -S u1 \ --s-u1-stream=src_relay \ --s-u1-socket_type=SOCK_DGRAM \ --s-u1-socket_protocol=udp \ --s-u1-port=1234 \ --s-u1-relay_socket_options="reuseaddr=1,broadcast=1" \ --s-u1-dst_host=192.168.0.255 --s-u1-dst_port=1235

• no and then..

The web server serves files and dynamic php content to a clients web browser. seeing most php/cgi scripts arent expecting to be run in cli mode with cgi emulation, some logic in your php code you want interpreted may need some case handling for sonic www. ie. pretty much any code that will result in an uncontrolled ob_flush() or header buffer alteration. eg. premature exiting, error handling, setting cookies etc. as well as the pseudo cgi environment, your top level main php file that is being executed, will now be a second level include under the main sonic stream module class. ie. some functions may need to be preparsed top most of file, aswell as re-scoping most top level variables to globals. there is a small (and probably outdated) compatibility list to preview before attempting to auto-patch with the supplied script.

• v0.2.3+ Daemon: pthread friendly ie. you are able to call pcntl_fork() from within your php/cgi scripts
• v0.2.8+ WWW: able to be configured as a UDP web-server (see STREAM MAP below)

STREAM MAP - unicast. multicast. asymmetric socket I/O (multiplex/mux) sock_in www | | | | | | | | --> | udp | ---------------------> | udp | <-> | tcp | <--------------------> | tcp | client_ip:client_port |________| | | ip:port _______ | | <-- | tcp/ | <--------------------- | tcp/ | | udp | | udp | mux_host:mux_port | | |mux_any| | | [mux_src] sock_out [ tcp-1 ] <<-------------------------->> [ tcp-1 ] [ udp/ ] [ ] [ tcp-1 ] >>-------------------------->> [ udp/ ] [ tcp-1 ] [ udp/ ] <<--------------------------<< [ ] [ tcp-2 ] [ ]

; web server: www.ini ; or merged into default main conf sonic.ini ;// ; set services to load services = www1, www2 ; service www1 - sonic generic service-www1-stream = www service-www1-max = 5 service-www1-ip = 0.0.0.0 service-www1-port = 81 ; service www1 - stream module specific service-www1-document_root = /path/to/www1 service-www1-server_admin = webmaster@localhost ; service www1 - virtual hosts service-www1-vhosts = v1, v2 ; service www1-v1 - virtual host service-www1-v1-host = 10.0.0.1:81 service-www1-v1-document_root = /path/to/virtual/www1 service-www1-v2-server_admin = webmaster@localhost ; service www1-v2 - virtual host service-www1-v2-host = host.domain.com:81 service-www1-v2-document_root = /path/to/virtual/www2 service-www1-v2-server_admin = webmaster@localhost ; service www2 - sonic generic service-www2-stream = www service-www2-max = 5 service-www2-ip = 127.0.0.1 service-www2-port = 82 service-www2-document_root = /path/to/www2 service-www2-server_admin = webmaster@localhost

• (almost dont care) sonic_www_php_session_start check http_buff on first call, throw error like convention
• (dont care) use placeholder for socket lock, and conf as optional
• (dont care) use threaded/ALARM method for better wait timeout eg. DDOS
• (next release) 304 Not Modified
• (dont care) handle HEAD request
• continue to hash out http 1.x environment / pseudo cgi, eg. _FATAL_ Errors
• aaaaaand den?..
• extra server configuration eg. +Index, filters, .ht* will be extremely unlikely use nanoweb or PHP workarounds