Preface

The YtFlowCore Book is prepared for those who want to customize their YtFlowCore (or its UI front ends like YtFlowApp) Profiles.

Prerequisites

To edit YtFlow profiles, you may need a dedicated editor. YtFlowApp has a built-in configuration editor. The ytflow-edit TUI tool from YtFlowCore also works.

Although we are trying to minimize necessary prior knowledge, understanding of network fundamentals can greatly improve your experience while exploring YtFlow. You are not expected to be a network expert (while some of you already are) to get started, as long as you can tell the difference between TCP and UDP.

Since we present plugin parameters with JSON, you will need to get familiar with the JSON format. Can you spot a mistake in this JSON document?

#![allow(unused)]
fn main() {
use serde_json::{from_str, Value};
let s = r#"
{
    "host": "localhost",
    "port": 1080,
    "password": "password",
    "tcp_next": "socket",
}
"#;
println!("{:?}", from_str::<Value>(&s[1..]));
}

About This Book

The YtFlowCore Book is open source and available at GitHub. Feel free to contribute by submitting a new issue to request clarification, or making pull requests to fix typos.

This work is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License.

Introduction

YtFlowCore is a modern proxy framework that allows heavy customization. You can design your own network flow by chaining plugins and tuning parameters. Expert users will find it interesting to play around with custom profiles, while novice users may choose to benefit from preset configurations that our UI front end, such as YtFlowApp, has set up for you.

To achieve maximum flexibility, the plugins are designed with KISS principle in mind. Sometimes, you will find it cumbersome to deploy so many plugins, only to achieve something appears as a simple button in other apps. However, such explicitness avoids confusion when you debug and customize your network. For example, the FakeIP infrastructure can be decomposed into:

A simple dispatcher that hijacks all DNS requests,
A FakeIP DNS resolver, providing fake IP addresses and corresponding domain names, and
A DNS server, acting as 'FakeDNS', and responsible for translating mapped FakeIPs back into domain names from incoming connections.

These plugins are fully configurable, and work intuitively in your profile. Let's say you want to implement split routing based on countries/regions of destination addresses using rule-dispatcher. In order to lookup geolocations from the database, you will need a real-IP DNS resolver to get IP addresses associated with domain names. You may ask, "will the real-IP DNS resolver mess up with the FakeIP one?" The answer is, no. In this profile, a destination address will only be overwritten by the destination resolver, while DNS resolvers do no change the destination address. You will learn more about plugins in Chapter 4.

Revision History

2023-06-05: Added link to rule-dispatcher.

Basics

In this chapter, we will cover basic concepts in YtFlowCore.

Profile and Plugin

Profile and Plugin are two core entities in YtFlow. When YtFlowCore launches, it retrieves the specified profile from the database, along with all plugins included in the profile. Then, the plugins are loaded and started to respond to incoming connections. Errors occur during parsing or loading plugins will be reported to the user. In this case, YtFlowCore may or may not reject running the profile, depending on the implementation.

Profile

A profile consists of a collection of plugins that collectively defines runtime behavior of YtFlowCore. There is not too much interesting fields inside a profile itself. Instead, you may customize the network flow by modifying the plugins.

Remember that a YtFlowCore instance only runs one profile at a time. If you want to switch to a different profile, you will need to restart the YtFlowCore instance, or reconnect through the UI.

Plugin

A plugin in a profile is an atomic instance of certain functions, such as stream encoding and decoding, destination rewrite, and dispatching to different plugins. They are designed to be as small as possible, so that you can make the most of them by chaining them in a creative way.

You may have already noticed that outbound client plugins, such as shadowsocks-client and socks5-client, care nothing about which address or port your proxy server is running on. They only encode destination addresses into the streams, but do not change the destination. To redirect all streams to the proxy server, you will need a redirect plugin.

Note that plugins are a integrated part of YtFlowCore. Currently, there is no such mechanism to dynamically load a new type of plugin from a shared library.

Platform	Socket bind	Network change monitoring	Host name resolution
macOS/iOS	`IP_BOUND_IF` / `IPV6_BOUND_IF`	`nw_path_monitor_t`	dnssd
Windows	socket bind to interface address	`Windows.Networking.Connectivity.NetworkInformation.NetworkStatusChanged`	`host_resolver` via DNS addresses of the interface
Linux	`SO_BINDTODEVICE`	`netlink`	systemd-resolved D-Bus API, fallback to `host-resolver` via DNS addresses of the interface retrieved from NetworkManager D-Bus API