Notes

This is a kind of specification documentation base on what I need and how to use it.

ZFS Stream Parsing

First thing first. ZFS library for Erlang was made to easily parse ZFS send/receive stream and split it in small piece.

Parsing a zfs stream should be simple and return standard and comprehensible data-structure.

zfs_stream:parse(Stream).

Sometime, our ZFS stream is a bit larger than expected, so, we can filter it. This filtering will be done with Erlang Match syntax.

zfs_stream:parse(Stream, [{'object', '_'}]).

Specific Stream Parsing Feature

zfs_stream:parse(Stream, []).

ZFS Stream is a complex data-structure containing different type of objects. We can parse it independantly of each others.

% dmu replay record is a full
% zfs stream sent from zfs send command
dmu_replay_record:parse(Stream).
dmu_replay_record:parse(Stream, _Opts).

% drr_begin is the first data structure
% used in ZFS Stream and contain common
% information about this stream
drr_begin:parse(Stream).
drr_begin:parse(Stream; _Opts).

% drr_end
drr_end:parse(Stream).
drr_end:parse(Stream, _Opts).

% drr_object
drr_object:parse(Stream).
drr_object:parse(Stream, _Opts).

% drr_freeobjects
drr_freeobjects:parse(Stream).
drr_freeobjects:parse(Stream, _Opts).

% drr_write
drr_write:parse(Stream).
drr_write:parse(Stream, _Opts).

% drr_write_byref
drr_write_byref:parse(Stream).
drr_write_byref:parse(Stream, _Opts).

% drr_free
drr_free:parse(Stream).
drr_free:parse(Stream, _Opts).

% drr_spill
drr_spill:parse(Stream).
drr_spill:parse(Stream, _Opts).

Those functions return erlang map data-structure only if the stream or part of the stream is the right object. dmu_replay_record:parse/1 parse an entire ZFS stream and is equivalent with zfs_stream:parse/1 function.

ZFS Stream Splitting

A ZFS Stream is a range of ordered transactional ZFS objects. This library is made to split stream in small pieces.

zfs_stream:split(Stream).
zfs_stream:split(Stream, _Opts).

You can split it in different way, just split all logical part in bitstring or parse each part with erlang abstraction.

zfs_stream:split(Stream, [bitstring]).
zfs_stream:split(Stream, [map]).

ZFS Stream Analysing

All ZFS data-structure are delivered with checksum, analyzing it give us the change to validate every piece of a stream based on checksum.

zfs_stream:analyze(Stream).
zfs_stream:analyze(Stream, _Opts).

ZFS Stream Crafting

If we have the possibility to analyze or read a stream, we have also the possibility to craft any kind of ZFS stream from scratch.

zfs_stream:craft(Type, Content).

ZFS Stream Fuzzing

ZFS is executed in Kernel Land, if something goes wrong, in the best case, system crash, in the worst case, an attacker can install a rootkit or gain privilege access to our server. Fuzzing is a technique used widely on security to check program inputs.

This high level library give us the possibility to randomly craft ZFS stream and check them but also alterate an existing one.

% create a totally random zfs stream from scratch
zfs_stream:fuzz().

% generete an object stream based on Type
zfs_stream:fuzz(Type).

% extra options 
zfs_stream:fuzz(Type, _Opts).
zfs_stream:fuzz(Type, [{destination, Destination}
                      ,{source, Source}
                      ,{alter, []}
                      ,{format, Format}]).

3.5 KiB Raw Permalink Blame History